tapimo 0.14.0 → 0.15.0

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

@@ -1,4 +1,3 @@
-// TODO(tidx-v1): Restore `queryOutbound` from commit `de87725` after TIDX v1 ships. Remove the receipt-side merge and bounded follow-up lookup.
 import { Hono } from 'hono';
 import { Address, Hex } from 'ox';
 import { parseEventLogs, zeroAddress } from 'viem';
@@ -1266,6 +1265,10 @@ export var schema;
     });
     /** A single classified activity item. */
     schema.Item = OpenApi.component(z.union(schema.items).check(z.describe('One classified activity item in the address feed.')), 'ActivityItem');
+    /** Public activity types accepted by the address feed's `type` filter. */
+    schema.ActivityType = z
+        .enum(schema.items.map((item) => item.shape.type.def.values[0]))
+        .check(z.describe('A classified activity type.'));
     /** A folded access-key group: consecutive same-signer items on one UTC day. */
     schema.Group = z
         .object({
@@ -1306,6 +1309,14 @@ export var schema;
         .check(z.describe('Additional activity resources and selection modes to include.'));
     /** Parses comma-separated optional activity resources and selection modes. */
     schema.includeQuery = Schema.includeQuery(schema.Include, 'Comma-separated activity options. `zones` combines the selected parent chain with every readable Zone.');
+    /** Parses comma-separated activity types with OR semantics. */
+    schema.typeQuery = Schema.includeQuery(schema.ActivityType, 'Only include these activity types, such as `transfer,swap`. Multiple values use OR semantics.');
+    const RawAmountBound = z
+        .optional(Schema.DecimalString)
+        .check(z.describe("A token quantity in the token's smallest unit."));
+    const ValuationAmountBound = z
+        .optional(z.string().check(z.regex(/^\d+(\.\d{1,6})?$/)))
+        .check(z.describe('A non-negative decimal amount in `valuation.currency`, with up to six decimal places.'), z.meta({ examples: ['1'] }));
     /** Schemas for the getAddressActivities operation. */
     let getAddressActivities;
     (function (getAddressActivities) {
@@ -1318,6 +1329,8 @@ export var schema;
         /** Query parameters for address activity requests. */
         getAddressActivities.Query = z
             .strictObject({
+            'amount.from': RawAmountBound.check(z.describe('Only include activities with at least one token amount greater than or equal to this base-unit quantity.')),
+            'amount.to': RawAmountBound.check(z.describe('Only include activities with at least one token amount less than or equal to this base-unit quantity.')),
             chainId: Schema.ChainIdQuery,
             cursor: Schema.Cursor,
             // Folding is opt-in: by default every item is returned at the root.
@@ -1331,9 +1344,39 @@ export var schema;
             logs: z
                 ._default(Schema.booleanQuery(), false)
                 .check(z.describe('Set to `true` to attach each item’s full transaction log set (decoded when possible) as a top-level `events` array, so no co-located log is hidden. Defaults to `false`. `unknown` items always include it.'), z.meta({ examples: [true] })),
+            recipient: z
+                .optional(Schema.Address)
+                .check(z.describe('Only include activities sent to this recipient address.')),
+            sender: z
+                .optional(Schema.Address)
+                .check(z.describe('Only include activities sent from this sender address.')),
+            token: z
+                .optional(Schema.TokenAddress)
+                .check(z.describe('Only include activities with a source, destination, or refund token for this TIP-20 contract.')),
+            type: schema.typeQuery,
+            'valuation.amount.from': ValuationAmountBound.check(z.describe('Only include activities with at least one valued amount greater than or equal to this amount. Requires `valuation.currency`.')),
+            'valuation.amount.to': ValuationAmountBound.check(z.describe('Only include activities with at least one valued amount less than or equal to this amount. Requires `valuation.currency`.')),
             'valuation.currency': Schema.Denomination,
         })
-            .check(z.describe('Query parameters for the address activity request. This feed uses cursor pagination only because activity classification can fold a variable number of rows into each entry, so positional `page` pagination would not be stable.'));
+            .check(z.refine((query) => {
+            const from = parseRawAmount(query['amount.from']);
+            const to = parseRawAmount(query['amount.to']);
+            return from === undefined || to === undefined || from <= to;
+        }, {
+            error: '`amount.from` must be less than or equal to `amount.to`.',
+            path: ['amount.from'],
+        }), z.refine((query) => (query['valuation.amount.from'] === undefined &&
+            query['valuation.amount.to'] === undefined) ||
+            query['valuation.currency'] !== undefined, {
+            error: '`valuation.currency` is required when filtering by valuation amount.',
+            path: ['valuation.currency'],
+        }), z.refine((query) => query['valuation.amount.from'] === undefined ||
+            query['valuation.amount.to'] === undefined ||
+            parseValuationAmount(query['valuation.amount.from']) <=
+                parseValuationAmount(query['valuation.amount.to']), {
+            error: '`valuation.amount.from` must be less than or equal to `valuation.amount.to`.',
+            path: ['valuation.amount.from'],
+        }), z.describe('Query parameters for the address activity request. This feed uses cursor pagination only because activity classification can fold a variable number of rows into each entry, so positional `page` pagination would not be stable.'));
         /**
          * Page of classified activity. Mirrors the wallet activity feed: a
          * newest-first list of `data` entries (items, or access-key groups when
@@ -1546,8 +1589,6 @@ const closeRequestedSelector = '0xf5a36fc00a96cbb9cf1f8f59299165e1d8ffffe94396d8
 // by the accountKeychain whenever a tx is signed by an access key. topic2 is the
 // access-key publicKey, i.e. the real signer.
 const accessKeySpendSelector = '0xe0815e3aaadddf4dd75bde97fc060f0c38afe18e87a169be86a3f5c28247f192';
-/** TIP-20 / ERC-20 `Transfer` event signature for the decoded CTE. */
-const transferSignature = 'event Transfer(address indexed from, address indexed to, uint256 value)';
 // Standard ERC-4626 vault events, absent from the merged `viem/tempo` ABI.
 // Decoding them lets external vault deposits/withdrawals classify instead of
 // falling through to the share-token mint/burn legs.
@@ -1574,21 +1615,17 @@ const erc4626Events = [
         type: 'event',
     },
 ];
-// TIP-20 payment-channel reserve precompile. Not exported by `viem/tempo`
-// `Addresses`, so the known address is pinned here: channel events
-// (`ChannelOpened`/`Settled`/`TopUp`/`ChannelClosed`) are emitted here, and
-// their paired TIP-20 `Transfer` legs use it as the funding counterparty, which
-// is how `channel-funded`/`channel-settled`/`channel-closed` recover the token.
-const tip20ChannelReserve = '0x4d50500000000000000000000000000000000000';
+const tip20ChannelReserve = Addresses.tip20ChannelReserve;
 // Tempo system addresses other than the DEX are never swap-route
 // counterparties; a newly shipped precompile joins the exclusion automatically.
-const nonRouteSystemAddresses = new Set([...Object.values(Addresses), tip20ChannelReserve]
-    .filter((value) => value !== Addresses.stablecoinDex)
+const nonRouteSystemAddresses = new Set(Object.values(Addresses)
+    .filter((value) => typeof value === 'string' && value !== Addresses.stablecoinDex)
     .map((value) => value.toLowerCase()));
 /** Number of grouped entries to target before stopping the page-fetch loop. */
 const minGroupEntries = 5;
 /** Largest number of items folded into a single access-key group. */
 const maxGroupSize = 50;
+const maxTokenAmount = 2n ** 256n - 1n;
 /** Token-bearing keys on an item's `data` payload, walked for enrichment. */
 const tokenKeys = ['destinationToken', 'refund', 'sourceToken'];
 const amountKeyByTokenKey = {
@@ -1596,6 +1633,72 @@ const amountKeyByTokenKey = {
     refund: 'refundAmount',
     sourceToken: 'sourceAmount',
 };
+function parseRawAmount(value) {
+    return value !== undefined && /^\d+$/.test(value) ? BigInt(value) : undefined;
+}
+/** Converts a decimal valuation amount to the API's fixed six-decimal scale. */
+function parseValuationAmount(value) {
+    const [whole, fraction = ''] = value.split('.');
+    return BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, '0'));
+}
+/** Returns whether an activity satisfies its participant and same-leg token predicates. */
+function matchesActivityFilter(item, filter) {
+    const data = item.data;
+    const recipient = data['recipient'];
+    if (filter.recipient !== undefined &&
+        (typeof recipient !== 'string' ||
+            !Address.isEqual(recipient, filter.recipient)))
+        return false;
+    const sender = data['sender'];
+    if (filter.sender !== undefined &&
+        (typeof sender !== 'string' || !Address.isEqual(sender, filter.sender)))
+        return false;
+    const amount = filter.amount;
+    if (amount === undefined && filter.token === undefined)
+        return true;
+    for (const key of tokenKeys) {
+        const token = data[key];
+        if (!token)
+            continue;
+        if (filter.token !== undefined && !Address.isEqual(token.address, filter.token))
+            continue;
+        const value = BigInt(token.amount);
+        if (amount?.from !== undefined && value < amount.from)
+            continue;
+        if (amount?.to !== undefined && value > amount.to)
+            continue;
+        return true;
+    }
+    return false;
+}
+/** Applies exact participant and same-leg token predicates after classification. */
+export function filterActivities(options) {
+    const { filter, items } = options;
+    return items.filter((item) => matchesActivityFilter(item, filter));
+}
+/** Returns whether any valued token leg in an activity falls within the requested range. */
+function matchesValuationAmount(item, bounds) {
+    if (bounds.from === undefined && bounds.to === undefined)
+        return true;
+    const data = item.data;
+    for (const key of Object.values(amountKeyByTokenKey)) {
+        const amount = data[key];
+        if (!amount || typeof amount !== 'object' || !('valuation' in amount))
+            continue;
+        const valuation = amount.valuation;
+        if (!valuation || typeof valuation !== 'object' || !('amount' in valuation))
+            continue;
+        if (typeof valuation.amount !== 'string')
+            continue;
+        const value = parseValuationAmount(valuation.amount);
+        if (bounds.from !== undefined && value < bounds.from)
+            continue;
+        if (bounds.to !== undefined && value > bounds.to)
+            continue;
+        return true;
+    }
+    return false;
+}
 /** Builds common public activity fields from the normalized transaction hash and representative log. */
 function baseFor(options) {
     return {
@@ -1672,17 +1775,67 @@ export function addresses(options = {}) {
             Cache.setPolicy(c, query.cursor === undefined ? Cache.policies.feed : Cache.policies.metadata);
         try {
             const chainId = query.chainId ?? c.get('chainId');
+            const amountBounds = {
+                from: parseRawAmount(query['amount.from']),
+                to: parseRawAmount(query['amount.to']),
+            };
+            const valuationBounds = {
+                from: query['valuation.amount.from'] === undefined
+                    ? undefined
+                    : parseValuationAmount(query['valuation.amount.from']),
+                to: query['valuation.amount.to'] === undefined
+                    ? undefined
+                    : parseValuationAmount(query['valuation.amount.to']),
+            };
+            const filterByValuation = valuationBounds.from !== undefined || valuationBounds.to !== undefined;
+            const activityFilter = {
+                ...(amountBounds.from !== undefined || amountBounds.to !== undefined
+                    ? { amount: amountBounds }
+                    : {}),
+                ...(query.recipient ? { recipient: query.recipient } : {}),
+                ...(query.sender ? { sender: query.sender } : {}),
+                ...(query.token ? { token: query.token } : {}),
+            };
+            const candidate = Object.keys(activityFilter).length > 0 ? activityFilter : undefined;
+            const types = new Set(query.type);
+            const refine = types.size > 0 || candidate ? (items) => filterActivities({ filter: activityFilter, items: items.filter((item) => types.size === 0 || types.has(item.type)) }) : undefined; // prettier-ignore
             const listed = await Timing.time(c, 'address_activities', async () => {
                 if (!query.include.includes('zones')) {
-                    const result = await Store.memoize((signal) => list(tidx({ chainId, signal, tidx: c.get('getTidx')(chainId) }), {
+                    const result = await Store.memoize((signal) => list(tidx({
+                        chainId,
+                        signal,
+                        tidx: c.get('getTidx')(chainId),
+                        time: (name, fn) => Timing.sum(c, name, fn),
+                    }), {
                         address: address,
                         cursor: query.cursor,
+                        ...(refine || filterByValuation || candidate
+                            ? {
+                                filter: {
+                                    candidate,
+                                    refine: async (items) => {
+                                        const filtered = refine ? refine(items) : [...items];
+                                        if (!filterByValuation)
+                                            return filtered;
+                                        const enriched = await enrichTokens(c, {
+                                            chainId,
+                                            denomination: query['valuation.currency'],
+                                            include: query.include,
+                                            items: filtered,
+                                            oracle,
+                                        });
+                                        return filtered.filter((_, index) => matchesValuationAmount(enriched.items[index], valuationBounds));
+                                    },
+                                },
+                            }
+                            : {}),
                         group: query.group,
                         limit: query.limit,
                         logs: query.logs,
                         store: c.get('store'),
+                        time: (name, fn) => Timing.sum(c, name, fn),
                     }), {
-                        key: `activities:v1:${chainId}:${address.toLowerCase()}:${query.group ?? false}:${query.logs ?? false}:${query.cursor ?? 'head'}:${query.limit}`,
+                        key: `activities:v4:${chainId}:${address.toLowerCase()}:${query.type.join(',')}:${query['amount.from'] ?? ''}:${query['amount.to'] ?? ''}:${query.recipient ?? ''}:${query.sender ?? ''}:${query.token ?? ''}:${query['valuation.amount.from'] ?? ''}:${query['valuation.amount.to'] ?? ''}:${query['valuation.currency'] ?? ''}:${query.group ?? false}:${query.logs ?? false}:${query.cursor ?? 'head'}:${query.limit}`,
                         store: c.get('store'),
                         ttl: Ttl.seconds(15),
                     });
@@ -1695,6 +1848,25 @@ export function addresses(options = {}) {
                 const result = await Store.memoize((signal) => listChains({
                     address: address,
                     cursor: query.cursor,
+                    ...(refine || filterByValuation || candidate
+                        ? {
+                            filter: {
+                                candidate,
+                                refine: async (items) => {
+                                    const filtered = refine ? refine(items) : [...items];
+                                    if (!filterByValuation)
+                                        return filtered;
+                                    const enriched = await enrichChainTokens(c, {
+                                        denomination: query['valuation.currency'],
+                                        include: query.include,
+                                        items: filtered,
+                                        oracle,
+                                    });
+                                    return filtered.filter((_, index) => matchesValuationAmount(enriched.items[index], valuationBounds));
+                                },
+                            },
+                        }
+                        : {}),
                     group: query.group,
                     limit: query.limit,
                     logs: query.logs,
@@ -1704,11 +1876,13 @@ export function addresses(options = {}) {
                             chainId,
                             signal,
                             tidx: c.get('getTidx')(chainId),
+                            time: (name, fn) => Timing.sum(c, name, fn),
                         }),
                     })),
                     store: c.get('store'),
+                    time: (name, fn) => Timing.sum(c, name, fn),
                 }), {
-                    key: `activities:zones:v2:${chainIds.join(',')}:${address.toLowerCase()}:${query.group ?? false}:${query.logs ?? false}:${query.cursor ?? 'head'}:${query.limit}`,
+                    key: `activities:zones:v5:${chainIds.join(',')}:${address.toLowerCase()}:${query.type.join(',')}:${query['amount.from'] ?? ''}:${query['amount.to'] ?? ''}:${query.recipient ?? ''}:${query.sender ?? ''}:${query.token ?? ''}:${query['valuation.amount.from'] ?? ''}:${query['valuation.amount.to'] ?? ''}:${query['valuation.currency'] ?? ''}:${query.group ?? false}:${query.logs ?? false}:${query.cursor ?? 'head'}:${query.limit}`,
                     store: c.get('store'),
                     ttl: Ttl.seconds(15),
                 });
@@ -2013,6 +2187,7 @@ async function classifyTransactionActivities(options) {
     const group = groupByTx(rows)[0];
     return classifyGroup(group, viewer, fingerprintMap, logs).map(withTitle);
 }
+const noAddressActivityTiming = async (_name, fn) => fn();
 /**
  * Lists classified activity for an address by running the shared pipeline
  * (`groupByTx` → `classifyGroup` → `enrichItem`) over rows from a
@@ -2021,10 +2196,11 @@ async function classifyTransactionActivities(options) {
  */
 export async function list(provider, options) {
     const { address, cursor, group = false, limit = 20, logs = false } = options;
+    const time = options.time ?? noAddressActivityTiming;
     const viewer = address.toLowerCase();
     // Best-effort MPP service directory: a fetch failure yields an empty map, so
     // enrichment never blocks the feed.
-    const fingerprintMap_promise = Mpp.fingerprintMap({ store: options.store }).catch(() => ({}));
+    const fingerprintMap_promise = time('address_activity_mpp', () => Mpp.fingerprintMap({ store: options.store })).catch(() => ({}));
     let currentCursor = cursor;
     const allItems = [];
     let hasMore = false;
@@ -2034,7 +2210,12 @@ export async function list(provider, options) {
     // measured against grouped entries (folding can collapse a page to very few),
     // otherwise against the raw item count.
     for (let attempt = 0; attempt < 3; attempt++) {
-        const { rows } = await provider.fetchRows({ address: viewer, cursor: currentCursor, limit });
+        const { rows } = await provider.fetchRows({
+            address: viewer,
+            cursor: currentCursor,
+            ...(options.filter?.candidate ? { filter: options.filter.candidate } : {}),
+            limit,
+        });
         const grouped = groupByTx(rows);
         const txGroups = grouped.slice(0, limit + 1);
         hasMore = txGroups.length > limit;
@@ -2042,7 +2223,8 @@ export async function list(provider, options) {
         const fingerprintMap = await fingerprintMap_promise;
         if (page.length === 0)
             break;
-        allItems.push(...page.flatMap((txGroup) => classifyGroup(txGroup, viewer, fingerprintMap, logs).map(withTitle)));
+        const classified = await time('address_activity_classify', () => page.flatMap((txGroup) => classifyGroup(txGroup, viewer, fingerprintMap, logs).map(withTitle)));
+        allItems.push(...(options.filter?.refine ? await options.filter.refine(classified) : classified));
         lastGroup = page[page.length - 1];
         const enough = group
             ? groupByAccessKeyItems(allItems).length >= minGroupEntries
@@ -2067,11 +2249,12 @@ const chainCursorVersion = 2;
 export async function listChains(options) {
     const { address, cursor, limit = 20, logs = false, providers, store } = options;
     const group = options.group ?? false;
+    const time = options.time ?? noAddressActivityTiming;
     const orderedProviders = [...providers].sort((a, b) => a.chainId - b.chainId);
     const chainIds = orderedProviders.map(({ chainId }) => chainId);
     const cursors = decodeChainCursor(cursor, chainIds);
     const viewer = address.toLowerCase();
-    const fingerprintMap_promise = Mpp.fingerprintMap({ store }).catch(() => ({}));
+    const fingerprintMap_promise = time('address_activity_mpp', () => Mpp.fingerprintMap({ store })).catch(() => ({}));
     const states = orderedProviders.map(({ chainId, provider }) => ({
         chainId,
         exhausted: false,
@@ -2087,6 +2270,7 @@ export async function listChains(options) {
             const { rows } = await state.provider.fetchRows({
                 address: viewer,
                 cursor: cursors.get(state.chainId),
+                ...(options.filter?.candidate ? { filter: options.filter.candidate } : {}),
                 limit,
             });
             const groups = groupByTx(rows).slice(0, limit + 1);
@@ -2108,14 +2292,19 @@ export async function listChains(options) {
         const fingerprintMap = await fingerprintMap_promise;
         if (page.length === 0)
             break;
-        for (const { state, txGroup } of page) {
-            state.groups.splice(state.groups.indexOf(txGroup), 1);
-            cursors.set(state.chainId, state.provider.cursorForGroup(txGroup));
-            allItems.push(...classifyGroup(txGroup, viewer, fingerprintMap, logs).map((item) => ({
-                ...withTitle(item),
-                chainId: state.chainId,
-            })));
-        }
+        const classified = await time('address_activity_classify', () => {
+            const items = [];
+            for (const { state, txGroup } of page) {
+                state.groups.splice(state.groups.indexOf(txGroup), 1);
+                cursors.set(state.chainId, state.provider.cursorForGroup(txGroup));
+                items.push(...classifyGroup(txGroup, viewer, fingerprintMap, logs).map((item) => ({
+                    ...withTitle(item),
+                    chainId: state.chainId,
+                })));
+            }
+            return items;
+        });
+        allItems.push(...(options.filter?.refine ? await options.filter.refine(classified) : classified));
         hasMore = states.some((state) => !state.exhausted || state.groups.length > 0);
         const enough = group
             ? groupByAccessKeyItems(allItems).length >= minGroupEntries
@@ -2131,6 +2320,7 @@ export async function listChains(options) {
         const { rows } = await state.provider.fetchRows({
             address: viewer,
             cursor: cursors.get(state.chainId),
+            ...(options.filter?.candidate ? { filter: options.filter.candidate } : {}),
             limit: 1,
         });
         const group = groupByTx(rows)[0];
@@ -2171,16 +2361,13 @@ function encodeChainCursor(cursors, chainIds) {
     ]);
 }
 /**
- * Creates a TIDX-backed {@link Provider} that runs three sub-queries in
- * parallel and merges them:
- * - Q1 (outbound): page receipts where the address is `from` or `fee_payer`,
- *   then fetch the selected transactions' logs with a bounded lookup.
- * - Q2 (inbound): decoded `Transfer` events to the address.
- * - Q3 (outbound transfers): decoded `Transfer` events from the address
- *   (catches access-key-signed sends where `tx.from` differs from the address).
+ * Creates a TIDX-backed {@link Provider} that runs two sub-queries in parallel:
+ * one joins bounded outbound transactions to their logs, and one reads inbound
+ * and outbound `Transfer` logs.
  */
 export function tidx(deps) {
     const { chainId, signal, tidx: tidxClient } = deps;
+    const time = deps.time ?? noAddressActivityTiming;
     const fetch = (options) => {
         const requestSignal = signal && options.signal
             ? AbortSignal.any([signal, options.signal])
@@ -2199,179 +2386,287 @@ export function tidx(deps) {
             return undefined;
         return { blockNum: decoded[0], txIdx: decoded[1] };
     }
-    /**
-     * Q1 pages outbound receipts, then fetches their logs by bounded block range
-     * and transaction hash. The cursor preserves block and transaction index order.
-     */
+    /** Q1 joins bounded outbound transactions to their logs. */
     async function queryOutbound(options) {
         const { address, cursor, limit } = options;
-        const keyset = cursor
+        const receiptKeyset = cursor
             ? `AND block_num <= ${cursor.blockNum} AND (block_num < ${cursor.blockNum} OR tx_idx < ${cursor.txIdx})`
             : '';
         const queryLimit = limit + 1;
-        const fetchReceipts = (side) => fetch({
+        const txKeyset = cursor
+            ? `AND block_num <= ${cursor.blockNum} AND (block_num < ${cursor.blockNum} OR idx < ${cursor.txIdx})`
+            : '';
+        const result = await time('address_activity_outbound', () => fetch({
             chainId,
             // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
             // to `string`.
             query: `
-          SELECT tx_hash, block_num, block_timestamp, tx_idx, "from", fee_payer
-          FROM receipts
-          WHERE "${side}" = '${address}' ${keyset}
-          ORDER BY block_num DESC, tx_idx DESC
-          LIMIT ${queryLimit}
+          WITH outbound_candidates AS (
+            (SELECT hash AS tx_hash, block_num, block_timestamp, idx AS tx_idx, "from", fee_payer
+             FROM txs
+             WHERE "from" = '${address}' ${txKeyset}
+             ORDER BY block_num DESC, idx DESC
+             LIMIT ${queryLimit})
+            UNION
+            (SELECT tx_hash, block_num, block_timestamp, tx_idx, "from", fee_payer
+             FROM receipts
+             WHERE fee_payer = '${address}' ${receiptKeyset}
+             ORDER BY block_num DESC, tx_idx DESC
+             LIMIT ${queryLimit})
+          ), outbound AS (
+            SELECT tx_hash, block_num, block_timestamp, tx_idx, "from", fee_payer
+            FROM outbound_candidates
+            ORDER BY block_num DESC, tx_idx DESC
+            LIMIT ${queryLimit}
+          )
+          SELECT outbound.tx_hash, outbound.block_num, outbound.block_timestamp,
+            outbound.tx_idx, outbound."from", outbound.fee_payer, logs.log_idx,
+            logs.address, logs.selector, logs.topic1, logs.topic2, logs.topic3, logs.data
+          FROM outbound
+          INNER JOIN logs
+            ON logs.tx_hash = outbound.tx_hash AND logs.block_num = outbound.block_num
+          ORDER BY outbound.block_num DESC, outbound.tx_idx DESC, logs.log_idx ASC
         `,
-        });
-        // Fetching `limit + 1` from each side is sufficient to form the newest
-        // `limit + 1` transactions after the two ordered sets are merged.
-        const [paid, sent] = await Promise.all([fetchReceipts('fee_payer'), fetchReceipts('from')]);
-        const seen = new Set();
-        const receipts = [...paid.rows, ...sent.rows]
-            .map((r) => ({
+        }));
+        return result.rows.map((r) => ({
             blockNum: Number(Value.toNumber(r['block_num'])),
             blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
+            data: Value.toText(r['data']) ?? null,
             feePayer: lowerOrNull(r['fee_payer']),
+            logAddress: lower(r['address']),
+            logIdx: Number(Value.toNumber(r['log_idx'])),
+            selector: Value.toText(r['selector']) ?? null,
+            source: 'q1',
+            topic1: Value.toText(r['topic1']) ?? null,
+            topic2: Value.toText(r['topic2']) ?? null,
+            topic3: Value.toText(r['topic3']) ?? null,
             txHash: lowerHash(r['tx_hash']),
             txIdx: Number(Value.toNumber(r['tx_idx'])),
             txSender: lowerOrNull(r['from']),
-        }))
-            .filter((receipt) => {
-            if (seen.has(receipt.txHash))
-                return false;
-            seen.add(receipt.txHash);
-            return true;
-        })
-            .sort((a, b) => {
-            if (a.blockNum !== b.blockNum)
-                return b.blockNum - a.blockNum;
-            return b.txIdx - a.txIdx;
-        })
-            .slice(0, queryLimit);
-        if (receipts.length === 0)
-            return [];
-        const blocks = receipts.map((receipt) => receipt.blockNum);
-        const receiptByHash = new Map(receipts.map((receipt) => [receipt.txHash, receipt]));
-        const txHashes = receipts.map((receipt) => `'${receipt.txHash}'`).join(', ');
-        // `logs` is not keyed by transaction hash, so pair the bounded hash list
-        // with the selected receipts' block range to avoid a full archive scan.
-        const logs = await fetch({
-            chainId,
-            // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
-            // to `string`.
-            query: `
-        SELECT tx_hash, block_num, tx_idx, log_idx, address, selector, topic1, topic2, topic3, data
-        FROM logs
-        WHERE block_num BETWEEN ${Math.min(...blocks)} AND ${Math.max(...blocks)}
-          AND tx_hash IN (${txHashes})
-        ORDER BY block_num DESC, tx_idx DESC, log_idx ASC
-      `,
-        });
-        const rows = logs.rows.flatMap((r) => {
-            const receipt = receiptByHash.get(lowerHash(r['tx_hash']));
-            if (!receipt)
-                return [];
-            return [
-                {
-                    blockNum: receipt.blockNum,
-                    blockTimestamp: receipt.blockTimestamp,
-                    data: Value.toText(r['data']) ?? null,
-                    feePayer: receipt.feePayer,
-                    logAddress: lower(r['address']),
-                    logIdx: Number(Value.toNumber(r['log_idx'])),
-                    selector: Value.toText(r['selector']) ?? null,
-                    source: 'q1',
-                    topic1: Value.toText(r['topic1']) ?? null,
-                    topic2: Value.toText(r['topic2']) ?? null,
-                    topic3: Value.toText(r['topic3']) ?? null,
-                    txHash: receipt.txHash,
-                    txIdx: receipt.txIdx,
-                    txSender: receipt.txSender,
-                },
-            ];
-        });
-        return mergeAndSort(rows, [], []);
+        }));
     }
-    /** Q2/Q3: decoded `Transfer` events on one side of the address. */
+    /** Q2 reads inbound and outbound `Transfer` logs in one request. */
     async function queryTransfers(options) {
-        const { address, cursor, limit, side } = options;
-        const where = side === 'inbound'
-            ? `"to" = '${address}' AND "from" != '${address}'`
-            : `"from" = '${address}' AND "to" != '${address}'`;
-        const keyset = cursor ? `AND block_num < ${cursor.blockNum}` : '';
-        const query = (blockKey) => `
-        SELECT "from", "to", address, value, tx_hash, block_num, block_timestamp, log_idx, tx_idx
-        FROM Transfer
-        WHERE ${where} ${keyset}
-        ${blockKey ? `ORDER BY ${blockKey} DESC, tx_idx DESC` : ''}
-        LIMIT ${blockKey ? limit * 4 : Schema.countCap}
-      `;
-        const result = await (async () => {
+        const { address, cursor, filter, limit } = options;
+        const keyset = cursor
+            ? `AND (block_num < ${cursor.blockNum} OR (block_num = ${cursor.blockNum} AND tx_idx < ${cursor.txIdx}))`
+            : '';
+        const amount = filter?.amount;
+        const participantPredicates = [
+            ...(filter?.recipient !== undefined ? [`"to" = '${filter.recipient}'`] : []),
+            ...(filter?.sender !== undefined ? [`"from" = '${filter.sender}'`] : []),
+        ];
+        const materializedPredicate = [
+            ...participantPredicates,
+            ...(filter?.token !== undefined ? [`token = '${filter.token}'`] : []),
+            ...(amount?.from !== undefined
+                ? amount.from > maxTokenAmount
+                    ? ['0']
+                    : [`toUInt256(amount) >= toUInt256('${amount.from}')`]
+                : []),
+            ...(amount?.to !== undefined && amount.to < maxTokenAmount
+                ? [`toUInt256(amount) <= toUInt256('${amount.to}')`]
+                : []),
+        ]
+            .map((predicate) => `AND ${predicate}`)
+            .join(' ');
+        const decodedPredicate = [
+            ...participantPredicates,
+            ...(filter?.token !== undefined ? [`address = '${filter.token}'`] : []),
+            ...(amount?.from !== undefined
+                ? amount.from > maxTokenAmount
+                    ? ['0']
+                    : [`value >= ${amount.from}`]
+                : []),
+            ...(amount?.to !== undefined && amount.to < maxTokenAmount ? [`value <= ${amount.to}`] : []),
+        ]
+            .map((predicate) => `AND ${predicate}`)
+            .join(' ');
+        const queryLimit = limit + 1;
+        const result = await time('address_activity_transfers', async () => {
             try {
                 return await fetch({
                     chainId,
-                    query: query('block_num'),
-                    signatures: [transferSignature],
+                    engine: 'clickhouse',
+                    // Bound transaction candidates first, then return every matching row
+                    // for each selected transaction so the group cursor cannot split one.
+                    query: `
+            WITH transfer_candidates AS (
+              (SELECT DISTINCT tx_hash, block_num, tx_idx
+               FROM token_transfers
+               WHERE "to" = '${address}' AND "from" != '${address}' ${materializedPredicate} ${keyset}
+               ORDER BY block_num DESC, tx_idx DESC
+               LIMIT ${queryLimit})
+              UNION DISTINCT
+              (SELECT DISTINCT tx_hash, block_num, tx_idx
+               FROM token_transfers
+               WHERE "from" = '${address}' AND "to" != '${address}' ${materializedPredicate} ${keyset}
+               ORDER BY block_num DESC, tx_idx DESC
+               LIMIT ${queryLimit})
+            ), selected_transactions AS (
+              SELECT tx_hash, block_num, tx_idx
+              FROM transfer_candidates
+              ORDER BY block_num DESC, tx_idx DESC
+              LIMIT ${queryLimit}
+            )
+            SELECT DISTINCT indexed.token AS address,
+              toString(toUInt256(indexed.amount)) AS amount, indexed.tx_hash, indexed.block_num,
+              toUnixTimestamp(indexed.block_timestamp) AS block_timestamp_unix,
+              indexed.log_idx, indexed.tx_idx, indexed."from", indexed."to"
+            FROM token_transfers AS indexed
+            INNER JOIN selected_transactions AS selected
+              ON selected.tx_hash = indexed.tx_hash AND selected.block_num = indexed.block_num
+                AND selected.tx_idx = indexed.tx_idx
+            WHERE (indexed."to" = '${address}' AND indexed."from" != '${address}')
+              OR (indexed."from" = '${address}' AND indexed."to" != '${address}')
+            ORDER BY indexed.block_num DESC, indexed.tx_idx DESC, indexed.log_idx DESC
+          `,
                 });
             }
             catch (error) {
-                if (!Tidx.isDeterministicError(error))
+                // Older indexers reject materialized address scans. Retain the decoded
+                // Transfer source so activity feeds remain available on those chains.
+                if (!Tidx.isQueryRejection(error))
                     throw error;
-                try {
-                    // The expression blocks a mis-selected block-ordered top-N walk.
-                    return await fetch({
-                        chainId,
-                        query: query('block_num + 0'),
-                        signatures: [transferSignature],
-                    });
-                }
-                catch (fallbackError) {
-                    if (!Tidx.isDeterministicError(fallbackError))
-                        throw fallbackError;
-                    const result = await fetch({
-                        chainId,
-                        query: query(),
-                        signatures: [transferSignature],
-                    });
-                    // An unordered sample cannot safely produce an activity cursor.
-                    if (result.rows.length >= Schema.countCap)
-                        throw fallbackError;
-                    return result;
-                }
+                const predicates = [
+                    `"to" = '${address}' AND "from" != '${address}'`,
+                    `"from" = '${address}' AND "to" != '${address}'`,
+                ];
+                const fetchDecoded = async (predicate, queryLimit) => {
+                    const where = `WHERE ${predicate} ${decodedPredicate}`;
+                    try {
+                        return await fetch({
+                            chainId,
+                            query: `
+                SELECT DISTINCT tx_hash, block_num, tx_idx
+                FROM Transfer
+                ${where}
+                ORDER BY block_num DESC, tx_idx DESC
+                LIMIT ${queryLimit}
+              `,
+                            signatures: [Transfers.signature],
+                        });
+                    }
+                    catch (error) {
+                        // Match the transfer feed's bounded fallback when sparse decoded
+                        // top-N queries are rejected by an older indexer.
+                        if (!Tidx.isDeterministicError(error))
+                            throw error;
+                        const sample = await fetch({
+                            chainId,
+                            query: `
+                SELECT DISTINCT tx_hash, block_num, tx_idx
+                FROM Transfer
+                ${where}
+                LIMIT ${Schema.countCap}
+              `,
+                            signatures: [Transfers.signature],
+                        });
+                        // An unordered sample is safe only when complete. At the cap,
+                        // preserve the rejection rather than issue a cursor that can skip rows.
+                        if (sample.rows.length >= Schema.countCap)
+                            throw error;
+                        return {
+                            rows: sample.rows
+                                .sort((a, b) => Number(b['block_num']) - Number(a['block_num']) ||
+                                Number(b['tx_idx']) - Number(a['tx_idx']))
+                                .slice(0, queryLimit),
+                        };
+                    }
+                };
+                const rows = await Promise.all(predicates.map(async (predicate) => {
+                    const sameBlock = cursor
+                        ? `AND block_num = ${cursor.blockNum} AND tx_idx < ${cursor.txIdx}`
+                        : '';
+                    const first = await fetchDecoded(`${predicate} ${sameBlock}`, queryLimit);
+                    if (!cursor || first.rows.length >= queryLimit)
+                        return first.rows;
+                    const older = await fetchDecoded(`${predicate} AND block_num < ${cursor.blockNum}`, queryLimit - first.rows.length);
+                    return [...first.rows, ...older.rows];
+                }));
+                const candidates = rows
+                    .flat()
+                    .sort((a, b) => Number(b['block_num']) - Number(a['block_num']) ||
+                    Number(b['tx_idx']) - Number(a['tx_idx']));
+                const hashes = [...new Set(candidates.map((row) => lowerHash(row['tx_hash'])))].slice(0, queryLimit);
+                if (hashes.length === 0)
+                    return { rows: [] };
+                // Candidate limits count transactions. Hydrate all viewer transfers,
+                // including rows outside candidate filters, before classification.
+                const transfers = await fetch({
+                    chainId,
+                    query: `
+            SELECT address, value AS amount, tx_hash, block_num, block_timestamp,
+              log_idx, tx_idx, "from", "to"
+            FROM Transfer
+            WHERE tx_hash IN (${hashes.map((hash) => `'${hash}'`).join(', ')})
+              AND (("to" = '${address}' AND "from" != '${address}')
+                OR ("from" = '${address}' AND "to" != '${address}'))
+            LIMIT ${Schema.countCap}
+          `,
+                    signatures: [Transfers.signature],
+                });
+                // TIDX caps results even without a SQL limit. Never publish a page
+                // whose selected transactions might have been truncated by that cap.
+                if (transfers.rows.length >= Schema.countCap)
+                    throw error;
+                return transfers;
             }
-        })();
-        const rows = result.rows.map((r) => ({
-            blockNum: Number(Value.toNumber(r['block_num'])),
-            blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
-            data: null,
-            feePayer: null,
-            logAddress: lower(r['address']),
-            logIdx: Number(Value.toNumber(r['log_idx'])),
-            selector: null,
-            source: 'q2',
-            topic1: null,
-            topic2: null,
-            topic3: null,
-            transferAmount: BigInt(Value.toIntegerString(r['value']) ?? '0'),
-            transferFrom: lower(r['from']),
-            transferTo: lower(r['to']),
-            transferToken: lower(r['address']),
-            txHash: lowerHash(r['tx_hash']),
-            txIdx: Number(Value.toNumber(r['tx_idx'])),
-            txSender: null,
-        }));
-        return mergeAndSort([], rows, []).slice(0, limit * 4);
+        });
+        const rows = result.rows.flatMap((r) => {
+            const transferAmount = Value.toIntegerString(r['amount']);
+            const transferFrom = lowerOrNull(r['from']);
+            const transferTo = lowerOrNull(r['to']);
+            const blockTimestamp = (() => {
+                const value = r['block_timestamp_unix'] ?? r['block_timestamp'];
+                const numeric = Value.toNumber(value);
+                if (numeric !== undefined && Number.isFinite(numeric))
+                    return numeric;
+                const timestamp = Value.toIsoDateTime(value);
+                return timestamp === undefined ? undefined : Date.parse(timestamp) / 1_000;
+            })();
+            if (transferAmount === undefined ||
+                !transferFrom ||
+                !transferTo ||
+                blockTimestamp === undefined ||
+                !Number.isFinite(blockTimestamp))
+                return [];
+            return [
+                {
+                    blockNum: Number(Value.toNumber(r['block_num'])),
+                    blockTimestamp,
+                    data: null,
+                    feePayer: null,
+                    logAddress: lower(r['address']),
+                    logIdx: Number(Value.toNumber(r['log_idx'])),
+                    selector: null,
+                    source: 'q2',
+                    topic1: null,
+                    topic2: null,
+                    topic3: null,
+                    transferAmount: BigInt(transferAmount),
+                    transferFrom,
+                    transferTo,
+                    transferToken: lower(r['address']),
+                    txHash: lowerHash(r['tx_hash']),
+                    txIdx: Number(Value.toNumber(r['tx_idx'])),
+                    txSender: null,
+                },
+            ];
+        });
+        return mergeAndSort([], rows, []);
     }
     return {
         cursorForGroup(group) {
             return Cursor.encode([group.blockNum, group.txIdx]);
         },
-        async fetchRows({ address, cursor, limit }) {
+        async fetchRows({ address, cursor, filter, limit }) {
             const parsed = cursor ? parseCursor(cursor) : undefined;
-            const [q1, q2, q3] = await Promise.all([
+            const [q1, q2] = await Promise.all([
                 queryOutbound({ address, cursor: parsed, limit }),
-                queryTransfers({ address, cursor: parsed, limit, side: 'inbound' }),
-                queryTransfers({ address, cursor: parsed, limit, side: 'outbound' }),
+                queryTransfers({ address, cursor: parsed, filter, limit }),
             ]);
-            return { rows: mergeAndSort(q1, q2, q3) };
+            return { rows: mergeAndSort(q1, q2, []) };
         },
     };
 }
@@ -2742,7 +3037,7 @@ function classifyFromLogsCore(rows, ctx, events = decodeRows(rows)) {
         else
             takeEvent((e) => e.eventName === 'Deposited' && Address.isEqual(e.address, vault));
         claimVaultLegs(vault, [args.inputAmount, args.vaultAssets, args.earnShares]);
-        // The funding leg pays the router (the emitting contract), not the vault.
+        // The routes leg pays the router (the emitting contract), not the vault.
         claimVaultLegs(event.address, [args.inputAmount]);
         return { ...itemBase(event.logIndex), data, type: 'private-assets-deposited' };
     });
@@ -3435,7 +3730,7 @@ function classifyFromLogsCore(rows, ctx, events = decodeRows(rows)) {
         };
     });
     // Reward pool funded: the funded token is the emitting contract itself;
-    // claim the funding transfer.
+    // claim the route transfer.
     recognize(named('RewardDistributed'), (event) => {
         const args = event.args;
         takeTransfer((leg) => Address.isEqual(leg.address, event.address) &&
@@ -4030,7 +4325,7 @@ function decodeRows(rows) {
         // logs per log and can yield `args: undefined`; normalize so `in`-guards
         // never throw.
         return parseEventLogs({
-            abi: [...Abis.abis, ...Abis.earnRouter, ...Abis.earnVault, ...erc4626Events],
+            abi: [...Abis.core, ...Abis.earnRouter, ...Abis.earnVault, ...erc4626Events],
             logs,
             strict: false,
         }).map((event) => ({ ...event, args: event.args ?? {} }));
@@ -4119,9 +4414,15 @@ function collectTokens(item, set) {
 function getActivityTokenMetadata(c, options) {
     const { address, chainId } = options;
     if (address.startsWith(tip20AddressPrefix))
-        return Tokens.getTokenMetadata(c, { address, chainId });
-    return Store.memoize(async () => {
-        const metadata = await viem_Token.getMetadata(c.get('getClient')(chainId), { token: address });
+        return Tokens.getTokenMetadata(c, {
+            address,
+            chainId,
+            timeOrigin: (fn) => Timing.sum(c, 'activity_token_metadata_origin', fn),
+        });
+    return Store.memoize(() => Timing.sum(c, 'activity_token_metadata_origin', async () => {
+        const metadata = await viem_Token.getMetadata(c.get('getClient')(chainId), {
+            token: address,
+        });
         // ERC-20 has no currency field; its symbol is the amount's unit label.
         return {
             currency: metadata.symbol,
@@ -4129,7 +4430,7 @@ function getActivityTokenMetadata(c, options) {
             name: metadata.name,
             symbol: metadata.symbol,
         };
-    }, { key: `token:erc20:v1:${chainId}:${address}:metadata`, store: c.get('store'), ttl: Ttl.minutes(1) });
+    }), { key: `token:erc20:v1:${chainId}:${address}:metadata`, store: c.get('store'), ttl: Ttl.minutes(1) });
 }
 /** Resolves core metadata into immutable items. Optional logo and verification sources are best-effort. */
 async function enrichTokens(c, options) {
@@ -4139,16 +4440,20 @@ async function enrichTokens(c, options) {
         collectTokens(item, addresses);
     const includeLogoUri = include.includes('token.logoUri');
     const includeVerified = include.includes('token.verified');
-    const resolved_promise = addresses.size > 0
-        ? Timing.time(c, 'tokens', () => Promise.all([...addresses].map(async (address) => {
-            const [logoUri, metadata] = await Promise.all([
-                includeLogoUri
-                    ? Tokens.getTokenLogo(c, { address, chainId }).catch(() => undefined)
-                    : undefined,
-                getActivityTokenMetadata(c, { address, chainId }),
-            ]);
-            return { address: address.toLowerCase(), logoUri, metadata };
-        })))
+    const tokenAddresses = [...addresses];
+    const resolved_promise = tokenAddresses.length > 0
+        ? Timing.time(c, 'tokens', async () => {
+            const metadata_promise = Timing.sum(c, 'activity_token_metadata', () => Promise.all(tokenAddresses.map((address) => getActivityTokenMetadata(c, { address, chainId }))));
+            const logoUris_promise = includeLogoUri
+                ? Timing.sum(c, 'activity_token_logos', () => Promise.all(tokenAddresses.map((address) => Tokens.getTokenLogo(c, { address, chainId }).catch(() => undefined))))
+                : Promise.resolve(tokenAddresses.map(() => undefined));
+            const [metadata, logoUris] = await Promise.all([metadata_promise, logoUris_promise]);
+            return tokenAddresses.map((address, index) => ({
+                address: address.toLowerCase(),
+                logoUri: logoUris[index],
+                metadata: metadata[index],
+            }));
+        })
         : undefined;
     // Curated data is needed only for requested valuation or token fields.
     const snapshot_promise = addresses.size > 0 && (denomination !== undefined || includeLogoUri || includeVerified)