tapimo 0.7.1 → 0.8.0

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

@@ -1,3 +1,4 @@
+// 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';
@@ -12,6 +13,7 @@ import * as OpenApi from '../../../internal/OpenApi.js';
 import * as Response from '../../../internal/Response.js';
 import * as Schema from '../../../internal/Schema.js';
 import * as Store from '../../../internal/Store.js';
+import * as Tidx from '../../../internal/Tidx.js';
 import * as Timing from '../../../internal/Timing.js';
 import * as Ttl from '../../../internal/Ttl.js';
 import * as Value from '../../../internal/Value.js';
@@ -39,7 +41,7 @@ export var schema;
     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 ' +
+            .check(z.describe('The amount’s nominal value in the requested `valuation.currency`. `null` when the token is ' +
             'unverified, its display currency has no rate, or rates were unavailable.')),
     });
     /** Self-contained amount for a destination token. */
@@ -51,7 +53,7 @@ export var schema;
     /** Page-level resources: valuation rate provenance. */
     schema.Meta = z
         .object({
-        pricing: z
+        valuation: z
             .optional(Valuation.schema.Pricing)
             .check(z.describe('Rate provenance for amount valuations. Present when conversion rates were ' +
             'consulted; absent when every value was identity-valued or rates were unavailable.')),
@@ -1166,7 +1168,6 @@ export var schema;
             .strictObject({
             chainId: Schema.ChainIdQuery,
             cursor: Schema.Cursor,
-            denomination: Schema.Denomination,
             // Folding is opt-in: by default every item is returned at the root.
             group: z
                 ._default(Schema.booleanQuery(), false)
@@ -1178,6 +1179,7 @@ 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] })),
+            '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.'));
         /**
@@ -1209,13 +1211,13 @@ export var schema;
         getTransactionActivities.Query = z
             .strictObject({
             chainId: Schema.ChainIdQuery,
-            denomination: Schema.Denomination,
             include: schema.includeQuery,
             // Raw-log capture is opt-in: it can add a large `events` array to every
             // item, so the default response stays lean.
             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] })),
+            'valuation.currency': Schema.Denomination,
         })
             .check(z.describe('Query parameters for the transaction activity request.'));
         /**
@@ -1404,8 +1406,8 @@ function baseFor(options) {
  * Creates address-scoped activity handlers, mounted under the `/addresses`
  * composer. Exposes `GET /:address/activities`.
  *
- * Runs the full activity classification pipeline: three TIDX sub-queries
- * (outbound `receipts ⋈ logs`, inbound transfers, outbound transfers) merged
+ * Runs the full activity classification pipeline: outbound receipt/log
+ * lookups plus inbound and outbound transfer queries, merged
  * and decoded into typed items (`transfer`/`mint`/`burn`/`swap`/
  * `approval`/`session-closed`/`access-key-created`/`access-key-revoked`/
  * `token-created`/`burn-blocked`/`channel-opened`/`channel-funded`/
@@ -1478,7 +1480,7 @@ export function addresses(options = {}) {
             // Build immutable token and structured amount copies from RPC metadata.
             const { items, rates } = await enrichTokens(c, {
                 chainId,
-                denomination: query.denomination ?? 'USD',
+                denomination: query['valuation.currency'] ?? 'USD',
                 include: query.include,
                 items: unenrichedItems,
                 oracle,
@@ -1488,7 +1490,7 @@ export function addresses(options = {}) {
             const data = query.group ? groupByAccessKey(items) : items;
             return c.json(Response.validated(schema.getAddressActivities.Response, {
                 data,
-                ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+                ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
                 nextCursor,
             }), 200);
         }
@@ -1580,14 +1582,14 @@ export function transactions(options = {}) {
             // Build immutable token and structured amount copies from RPC metadata.
             const { items, rates } = await enrichTokens(c, {
                 chainId,
-                denomination: query.denomination ?? 'USD',
+                denomination: query['valuation.currency'] ?? 'USD',
                 include: query.include,
                 items: unenrichedItems,
                 oracle,
             });
             return c.json(Response.validated(schema.getTransactionActivities.Response, {
                 data: items,
-                ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+                ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
             }), 200);
         }
         catch (cause) {
@@ -1708,8 +1710,8 @@ export async function list(provider, options) {
 /**
  * Creates a TIDX-backed {@link Provider} that runs three sub-queries in
  * parallel and merges them:
- * - Q1 (outbound): `receipts ⋈ logs` for txs where the address is `from` or
- *   `fee_payer`, yielding full log rows.
+ * - 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).
@@ -1726,63 +1728,95 @@ export function tidx(deps) {
         return { blockNum: decoded[0], txIdx: decoded[1] };
     }
     /**
-     * Q1: every log of each transaction the address sent or paid the fee for,
-     * via a single `receipts ⋈ logs` join filtered on `from OR fee_payer`.
-     *
-     * The cursor uses a two-predicate keyset (`block_num <= N` AND `(block_num <
-     * N OR tx_idx < M)`) rather than a plain `block_num < N`: the `<= N` upper
-     * bound lets the ClickHouse planner seek to the cursor block on the
-     * `(block_num, tx_idx)` primary key instead of scanning from the tip, which
-     * is what avoids planner 422s on busy addresses. Over-fetch `limit * 4`
-     * (never `OFFSET`) because one tx fans out into many log rows that
-     * `groupByTx` collapses back into a single group.
+     * Q1 pages outbound receipts, then fetches their logs by bounded block range
+     * and transaction hash. The cursor preserves block and transaction index order.
      */
     async function queryOutbound(options) {
         const { address, cursor, limit } = options;
         const keyset = cursor
-            ? `AND receipts.block_num <= ${cursor.blockNum} AND (receipts.block_num < ${cursor.blockNum} OR receipts.tx_idx < ${cursor.txIdx})`
+            ? `AND block_num <= ${cursor.blockNum} AND (block_num < ${cursor.blockNum} OR tx_idx < ${cursor.txIdx})`
             : '';
-        // Raw-table join (no signature-decoded CTE), so inline SQL is cast to `string`.
-        const result = await tidxClient.fetch({
+        const queryLimit = limit + 1;
+        const fetchReceipts = (side) => tidxClient.fetch({
             chainId,
+            // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
+            // to `string`.
             query: `
-        SELECT
-          receipts.tx_hash AS tx_hash,
-          receipts.block_num AS block_num,
-          receipts.block_timestamp AS block_timestamp,
-          receipts.tx_idx AS tx_idx,
-          receipts."from" AS tx_sender,
-          receipts.fee_payer AS fee_payer,
-          logs.address AS log_address,
-          logs.selector AS selector,
-          logs.topic1 AS topic1,
-          logs.topic2 AS topic2,
-          logs.topic3 AS topic3,
-          logs.data AS data,
-          logs.log_idx AS log_idx
-        FROM receipts
-        INNER JOIN logs ON logs.tx_hash = receipts.tx_hash
-        WHERE (receipts."from" = '${address}' OR receipts.fee_payer = '${address}') ${keyset}
-        ORDER BY receipts.block_num DESC, receipts.tx_idx DESC
-        LIMIT ${limit * 4}
-      `,
+          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}
+        `,
         });
-        return result.rows.map((r) => ({
+        // 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) => ({
             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['log_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['tx_sender']),
-        }));
+            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 tidxClient.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. */
     async function queryTransfers(options) {
@@ -1791,18 +1825,48 @@ export function tidx(deps) {
             ? `"to" = '${address}' AND "from" != '${address}'`
             : `"from" = '${address}' AND "to" != '${address}'`;
         const keyset = cursor ? `AND block_num < ${cursor.blockNum}` : '';
-        const result = await tidxClient.fetch({
-            chainId,
-            query: `
+        const query = (blockKey) => `
         SELECT "from", "to", address, value, tx_hash, block_num, block_timestamp, log_idx, tx_idx
         FROM Transfer
         WHERE ${where} ${keyset}
-        ORDER BY block_num DESC, tx_idx DESC
-        LIMIT ${limit * 4}
-      `,
-            signatures: [transferSignature],
-        });
-        return result.rows.map((r) => ({
+        ${blockKey ? `ORDER BY ${blockKey} DESC, tx_idx DESC` : ''}
+        LIMIT ${blockKey ? limit * 4 : Schema.countCap}
+      `;
+        const result = await (async () => {
+            try {
+                return await tidxClient.fetch({
+                    chainId,
+                    query: query('block_num'),
+                    signatures: [transferSignature],
+                });
+            }
+            catch (error) {
+                if (!Tidx.isDeterministicError(error))
+                    throw error;
+                try {
+                    // The expression blocks a mis-selected block-ordered top-N walk.
+                    return await tidxClient.fetch({
+                        chainId,
+                        query: query('block_num + 0'),
+                        signatures: [transferSignature],
+                    });
+                }
+                catch (fallbackError) {
+                    if (!Tidx.isDeterministicError(fallbackError))
+                        throw fallbackError;
+                    const result = await tidxClient.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 rows = result.rows.map((r) => ({
             blockNum: Number(Value.toNumber(r['block_num'])),
             blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
             data: null,
@@ -1822,6 +1886,7 @@ export function tidx(deps) {
             txIdx: Number(Value.toNumber(r['tx_idx'])),
             txSender: null,
         }));
+        return mergeAndSort([], rows, []).slice(0, limit * 4);
     }
     return {
         cursorForGroup(group) {