tapimo 0.8.0 → 0.10.0

package/src/apps/data/routes/receipts.ts

@@ -553,22 +553,28 @@ export function receipts(options: receipts.Options = {}) {
 
           // Value each fee via its own currency tag, in the requested
           // denomination.
-          const denomination = query['valuation.currency'] ?? 'USD'
-          const rates = await Valuation.ratesFor(c, {
-            currencies: receipts.data.map((receipt) => receipt.feeAmount.currency),
-            denomination,
-            oracle,
-          })
+          const denomination = query['valuation.currency']
+          const rates = denomination
+            ? await Valuation.ratesFor(c, {
+                currencies: receipts.data.map((receipt) => receipt.feeAmount.currency),
+                denomination,
+                oracle,
+              })
+            : undefined
           const data = receipts.data.map((receipt) => ({
             ...receipt,
             feeAmount: {
               ...receipt.feeAmount,
-              valuation: Valuation.valuationFor({
-                amount: BigInt(receipt.feeAmount.baseUnits),
-                denomination,
-                rates,
-                token: receipt.feeAmount,
-              }),
+              ...(denomination
+                ? {
+                    valuation: Valuation.valuationFor({
+                      amount: BigInt(receipt.feeAmount.baseUnits),
+                      denomination,
+                      rates,
+                      token: receipt.feeAmount,
+                    }),
+                  }
+                : {}),
             },
           }))
 
@@ -680,22 +686,28 @@ export function receipts(options: receipts.Options = {}) {
 
           // Value the fee via its own currency tag, in the requested
           // denomination.
-          const denomination = query['valuation.currency'] ?? 'USD'
-          const rates = await Valuation.ratesFor(c, {
-            currencies: [enriched.feeAmount.currency],
-            denomination,
-            oracle,
-          })
+          const denomination = query['valuation.currency']
+          const rates = denomination
+            ? await Valuation.ratesFor(c, {
+                currencies: [enriched.feeAmount.currency],
+                denomination,
+                oracle,
+              })
+            : undefined
           const valued = {
             ...enriched,
             feeAmount: {
               ...enriched.feeAmount,
-              valuation: Valuation.valuationFor({
-                amount: BigInt(enriched.feeAmount.baseUnits),
-                denomination,
-                rates,
-                token: enriched.feeAmount,
-              }),
+              ...(denomination
+                ? {
+                    valuation: Valuation.valuationFor({
+                      amount: BigInt(enriched.feeAmount.baseUnits),
+                      denomination,
+                      rates,
+                      token: enriched.feeAmount,
+                    }),
+                  }
+                : {}),
             },
             meta: {
               ...enriched.meta,
@@ -771,9 +783,9 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
   return Timing.time(c, 'receipts', () =>
     Store.memoize(
       async () => {
-        // Page the `receipts` table alone, then enrich each row with the
-        // `type`/`fee_token` it does not store via a follow-up `txs` lookup
-        // (the blocks-feed pattern). Paging straight off `receipts` avoids the
+        // Page the `receipts` table alone. Fee-token queries read metadata
+        // denormalized on ClickHouse; other queries hydrate it from `txs`.
+        // Paging straight off `receipts` avoids the
         // `receipts JOIN txs` shape, which TIDX's planner cannot execute under
         // address scope: a `UNION` of two JOINs (or the `(from = X OR to = X)`
         // form) reliably returns `db error` (HTTP 422) for high-traffic
@@ -785,10 +797,9 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
         if (sender !== undefined) filters.push(`"from" = '${sender}'`)
         if (recipient !== undefined) filters.push(`"to" = '${recipient}'`)
         if (feePayer !== undefined) filters.push(`fee_payer = '${feePayer}'`)
-        // `fee_token` lives on `txs`, not `receipts`; filter via a subquery so
-        // the page query stays single-table.
-        if (feeToken !== undefined)
-          filters.push(`tx_hash IN (SELECT hash FROM txs WHERE fee_token = '${feeToken}')`)
+        // ClickHouse receipts denormalize fee metadata specifically to avoid
+        // an unbounded transaction-hash semi-join for this filter.
+        if (feeToken !== undefined) filters.push(`fee_token = '${feeToken}'`)
         if (fromBlock !== undefined) filters.push(`block_num >= ${fromBlock}`)
         if (toBlock !== undefined) filters.push(`block_num <= ${toBlock}`)
         if (fromTimestamp !== undefined) filters.push(`block_timestamp >= '${fromTimestamp}'`)
@@ -804,7 +815,7 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
 
         const columns = `block_num, block_timestamp, tx_idx, tx_hash, "from", "to",
                    contract_address, gas_used, cumulative_gas_used, effective_gas_price,
-                   status, fee_payer`
+                   status, fee_payer${feeToken === undefined ? '' : ', type, fee_token'}`
 
         // For address-scoped queries, run one branch per side and `UNION` so
         // each branch returns at most `limit + 1` index-ordered rows, the outer
@@ -814,14 +825,15 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
         //
         // The `receipts` table only indexes `from`, not `to` (a `to` scan over
         // ~25M rows hits the indexer's statement timeout and returns `db error`,
-        // HTTP 422). The `from` branch filters `receipts` directly; the `to`
-        // branch resolves matching transaction hashes from `txs` (which indexes
-        // `to`) and looks them up by the indexed `receipts.tx_hash`.
+        // HTTP 422). A fee-payer filter bounds the direct `to` scan through the
+        // receipt fee-payer index. Other `to` branches resolve matching hashes
+        // through the indexed `txs.to` and `receipts.tx_hash` columns.
         const sideQuery = (side: 'from' | 'to', addr: string) => {
-          const predicate =
-            side === 'from'
-              ? `"from" = '${addr}'`
-              : `tx_hash IN (SELECT hash FROM txs WHERE "to" = '${addr}')`
+          const predicate = (() => {
+            if (side === 'from') return `"from" = '${addr}'`
+            if (feePayer !== undefined) return `"to" = '${addr}'`
+            return `tx_hash IN (SELECT hash FROM txs WHERE "to" = '${addr}')`
+          })()
           const where = [predicate, ...filters].join(' AND ')
           // In the offset lane each branch over-fetches the full window
           // (`offset + limit + 1` rows) because the skip applies to the merged
@@ -847,7 +859,11 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
               LIMIT ${limit + 1}${skip}
             `
 
-        const result = await tidx.fetch({ chainId, query: query as string })
+        const result = await tidx.fetch({
+          chainId,
+          ...(feeToken !== undefined ? { engine: 'clickhouse' } : {}),
+          query: query as string,
+        })
 
         // The next page anchors below the last fetched row's `(block, tx_idx)`.
         const page = Cursor.paginate({
@@ -860,11 +876,8 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
           },
         })
 
-        // Enrich the page with `type`/`fee_token` from `txs` in a single
-        // `IN (...)` lookup scoped to the page's transaction hashes. `txs` is
-        // sorted by `(block_num, idx)` with no hash index, so the hash list
-        // must be paired with the page's block numbers — a bare `hash IN`
-        // full-scans the table.
+        // Enrich non-fee-token pages with metadata from `txs`. Pairing hashes
+        // with their blocks avoids a full-table hash scan.
         const hashes = [
           ...new Set(
             page.rows
@@ -880,7 +893,7 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
           ),
         ]
         const txByHash = new Map<string, { feeToken: unknown; type: unknown }>()
-        if (hashes.length > 0 && blocks.length > 0) {
+        if (feeToken === undefined && hashes.length > 0 && blocks.length > 0) {
           const txs = await tidx.fetch({
             chainId,
             query: `SELECT hash, type, fee_token FROM txs WHERE block_num IN (${blocks.join(
@@ -900,7 +913,8 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
         const data: humanizeReceipt.Output[] = []
         for (const row of page.rows) {
           const tx = typeof row['tx_hash'] === 'string' ? txByHash.get(row['tx_hash']) : undefined
-          const merged = { ...row, fee_token: tx?.feeToken, type: tx?.type }
+          const merged =
+            feeToken === undefined ? { ...row, fee_token: tx?.feeToken, type: tx?.type } : row
           const rpc = schema.Rpc.Receipt.safeParse(toRpcReceipt(merged))
           if (rpc.success) data.push(humanizeReceipt(rpc.data))
         }
@@ -950,8 +964,7 @@ function countFilters(options: countReceipts.Options): string[] {
   if (options.sender !== undefined) filters.push(`"from" = '${options.sender}'`)
   if (options.recipient !== undefined) filters.push(`"to" = '${options.recipient}'`)
   if (options.feePayer !== undefined) filters.push(`fee_payer = '${options.feePayer}'`)
-  if (options.feeToken !== undefined)
-    filters.push(`tx_hash IN (SELECT hash FROM txs WHERE fee_token = '${options.feeToken}')`)
+  if (options.feeToken !== undefined) filters.push(`fee_token = '${options.feeToken}'`)
   if (options.fromBlock !== undefined) filters.push(`block_num >= ${options.fromBlock}`)
   if (options.toBlock !== undefined) filters.push(`block_num <= ${options.toBlock}`)
   if (options.fromTimestamp !== undefined)
@@ -1003,7 +1016,11 @@ export function countReceipts(
             ) AS capped
           `
         }
-        const result = await tidx.fetch({ chainId, query: query as string })
+        const result = await tidx.fetch({
+          chainId,
+          ...(options.feeToken !== undefined ? { engine: 'clickhouse' } : {}),
+          query: query as string,
+        })
         const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0
         return { totalCountCapped: totalCount >= Schema.countCap, totalCount }
       },

package/src/apps/data/routes/tokens.test.ts

@@ -1121,6 +1121,57 @@ describe('GET /tokens/:token/transactions', () => {
     expect(secondBody.data.every((entry) => !firstHashes.has(entry.hash))).toBe(true)
   })
 
+  test('filters and counts by fee payer through receipts with pagination', async () => {
+    const client = app()
+    const seedResponse = await client.v1.tokens[':token'].transactions.$get(
+      { param: { token: TestApp.token }, query: { limit: '50' } },
+      TestApp.auth,
+    )
+    const seed = await TestApp.json(seedResponse, Tokens.schema.getTokenTransactions.Response)
+    const feePayers = seed.data.flatMap((transaction) => {
+      const feePayer = transaction.meta.rpc.feePayer
+      return typeof feePayer === 'string' ? [feePayer] : []
+    })
+    const feePayer = feePayers.find(
+      (candidate) => feePayers.filter((value) => value === candidate).length > 5,
+    )
+    if (!feePayer) return
+
+    const first = await client.v1.tokens[':token'].transactions.$get(
+      {
+        param: { token: TestApp.token },
+        query: { feePayer, include: 'totalCount', limit: '5' },
+      },
+      TestApp.auth,
+    )
+    const firstBody = await TestApp.json(first, Tokens.schema.getTokenTransactions.Response)
+    expect(first.status).toBe(200)
+    expect(first.headers.get('server-timing')).toContain('receipts;dur=')
+    expect(first.headers.get('server-timing')).toContain('receipts_count;dur=')
+    expect(firstBody.data).toHaveLength(5)
+    expect(firstBody.meta?.totalCount).toBeGreaterThanOrEqual(firstBody.data.length)
+    expect(firstBody.data.every((transaction) => transaction.meta.rpc.feePayer === feePayer)).toBe(
+      true,
+    )
+    if (!firstBody.nextCursor) return
+
+    const second = await client.v1.tokens[':token'].transactions.$get(
+      {
+        param: { token: TestApp.token },
+        query: { cursor: firstBody.nextCursor, feePayer, limit: '5' },
+      },
+      TestApp.auth,
+    )
+    const secondBody = await TestApp.json(second, Tokens.schema.getTokenTransactions.Response)
+    expect(second.status).toBe(200)
+    expect(secondBody.data.length).toBeGreaterThan(0)
+    expect(secondBody.data.every((transaction) => transaction.meta.rpc.feePayer === feePayer)).toBe(
+      true,
+    )
+    const firstHashes = new Set(firstBody.data.map((transaction) => transaction.hash))
+    expect(secondBody.data.every((transaction) => !firstHashes.has(transaction.hash))).toBe(true)
+  })
+
   test('returns 400 for an invalid token address', async () => {
     // The typed client requires `token: `Hex.Hex`` so an invalid literal
     // cannot pass through it; exercise the validator via `app.request`.

package/src/apps/data/routes/transactions.test.ts

@@ -311,6 +311,48 @@ describe('GET /transactions', () => {
     `)
   })
 
+  test('filters and counts by fee payer through receipts with pagination', async () => {
+    const client = TestApp.client()
+    const seedResponse = await client.v1.transactions.$get({ query: { limit: '50' } }, TestApp.auth)
+    const seed = await TestApp.json(seedResponse, Transactions.schema.getTransactions.Response)
+    const feePayers = seed.data.flatMap((transaction) => {
+      const feePayer = transaction.meta.rpc.feePayer
+      return typeof feePayer === 'string' ? [feePayer] : []
+    })
+    const feePayer = feePayers.find(
+      (candidate) => feePayers.filter((value) => value === candidate).length > 5,
+    )
+    if (!feePayer) return
+
+    const first = await client.v1.transactions.$get(
+      { query: { feePayer, include: 'totalCount', limit: '5' } },
+      TestApp.auth,
+    )
+    const firstBody = await TestApp.json(first, Transactions.schema.getTransactions.Response)
+    expect(first.status).toBe(200)
+    expect(first.headers.get('server-timing')).toContain('receipts;dur=')
+    expect(first.headers.get('server-timing')).toContain('receipts_count;dur=')
+    expect(firstBody.data).toHaveLength(5)
+    expect(firstBody.meta?.totalCount).toBeGreaterThanOrEqual(firstBody.data.length)
+    expect(firstBody.data.every((transaction) => transaction.meta.rpc.feePayer === feePayer)).toBe(
+      true,
+    )
+    if (!firstBody.nextCursor) return
+
+    const second = await client.v1.transactions.$get(
+      { query: { cursor: firstBody.nextCursor, feePayer, limit: '5' } },
+      TestApp.auth,
+    )
+    const secondBody = await TestApp.json(second, Transactions.schema.getTransactions.Response)
+    expect(second.status).toBe(200)
+    expect(secondBody.data.length).toBeGreaterThan(0)
+    expect(secondBody.data.every((transaction) => transaction.meta.rpc.feePayer === feePayer)).toBe(
+      true,
+    )
+    const firstHashes = new Set(firstBody.data.map((transaction) => transaction.hash))
+    expect(secondBody.data.every((transaction) => !firstHashes.has(transaction.hash))).toBe(true)
+  })
+
   test('filters reverted transactions by execution status', async () => {
     const client = TestApp.client()
     const response = await client.v1.transactions.$get(

package/src/apps/data/routes/transactions.ts

@@ -186,6 +186,12 @@ export namespace schema {
               'The chain ID that the transaction is valid on; legacy transactions may omit it.',
             ),
           ),
+        feePayer: z
+          .optional(Schema.Address)
+          .check(
+            z.describe('The address that paid the transaction fee.'),
+            z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
+          ),
         feePayerSignature: z
           .nullish(SignatureEnvelope)
           .check(
@@ -811,8 +817,8 @@ export function transactions() {
 
 /**
  * Lists humanized transactions with required fee-token metadata and opt-in
- * resources. Status filters page through receipts because execution status
- * lives there.
+ * resources. Status and fee-payer filters page through receipts because those
+ * fields are indexed there.
  */
 export async function listTransactions(
   c: Context<App.Environment>,
@@ -820,31 +826,28 @@ export async function listTransactions(
 ) {
   const { include, ...rest } = options
 
-  // `status` filters on the receipt's execution status, which `txs` does not
-  // store: page the receipts list (which already supports `status`) and hydrate
-  // each receipt's underlying transaction. The receipts `(block_num, tx_idx)`
-  // keyset cursor spans the same domain as the transactions `(block_num, idx)`
-  // cursor, so cursors stay interchangeable between the two paths.
-  const receiptPage =
-    rest.status === undefined
-      ? undefined
-      : await Receipts.getReceipts(c, {
-          address: rest.address,
-          chainId: rest.chainId,
-          cursor: rest.cursor,
-          feePayer: rest.feePayer,
-          feeToken: rest.feeToken,
-          fromBlock: rest.fromBlock,
-          fromTimestamp: rest.fromTimestamp,
-          limit: rest.limit,
-          order: rest.order,
-          page: rest.page,
-          recipient: rest.recipient,
-          sender: rest.sender,
-          status: rest.status,
-          toBlock: rest.toBlock,
-          toTimestamp: rest.toTimestamp,
-        })
+  // `status` lives on receipts, whose fee-payer index also avoids an unbounded
+  // `txs.fee_payer` scan. Its cursor matches the transaction cursor domain.
+  const receiptDriven = rest.status !== undefined || rest.feePayer !== undefined
+  const receiptPage = receiptDriven
+    ? await Receipts.getReceipts(c, {
+        address: rest.address,
+        chainId: rest.chainId,
+        cursor: rest.cursor,
+        feePayer: rest.feePayer,
+        feeToken: rest.feeToken,
+        fromBlock: rest.fromBlock,
+        fromTimestamp: rest.fromTimestamp,
+        limit: rest.limit,
+        order: rest.order,
+        page: rest.page,
+        recipient: rest.recipient,
+        sender: rest.sender,
+        status: rest.status,
+        toBlock: rest.toBlock,
+        toTimestamp: rest.toTimestamp,
+      })
+    : undefined
   const page = receiptPage
     ? {
         data: await transactionsForReceipts(c, {
@@ -885,7 +888,7 @@ export declare namespace listTransactions {
  * Fetches the underlying transactions for a page of receipts in one indexed
  * `txs` query and returns them humanized, ordered to match the receipt page.
  * Receipts whose transaction row is missing (not yet indexed) are skipped.
- * Backs the `status`-filtered transactions list, which pages receipts first.
+ * Backs status- and fee-payer-filtered lists, which page receipts first.
  */
 async function transactionsForReceipts(
   c: Context<App.Environment>,
@@ -1275,20 +1278,21 @@ function countFilters(options: countTransactions.Options): string[] {
 /**
  * Capped total count of transactions matching the same filters as the page.
  *
- * A `status` filter is delegated to {@link Receipts.countReceipts}, mirroring
- * the page's receipts-driven `status` path (execution status lives on receipts,
- * not `txs`). The address scope reuses the page's `UNION` of the two sides —
- * each side hits its own (`from`/`to`) index, and the deduped keyset count
- * avoids double-counting self-transactions (`from = to`). `totalCountCapped: true` is a
- * lower bound — at least {@link Schema.countCap} matches.
+ * Status and fee-payer filters are delegated to {@link Receipts.countReceipts},
+ * mirroring the page's receipts-driven path. The address scope reuses the
+ * page's `UNION` of the two sides; each side hits its own (`from`/`to`) index,
+ * and the deduped keyset count avoids double-counting self-transactions
+ * (`from = to`). `totalCountCapped: true` is a lower bound — at least
+ * {@link Schema.countCap} matches.
  */
 export function countTransactions(
   c: Context<App.Environment>,
   options: countTransactions.Options,
 ): Promise<z.output<typeof Schema.CountMeta>> {
-  // Status lives on receipts, so route the count through the same path the page
-  // uses: count receipts under the identical filters.
-  if (options.status !== undefined) return Receipts.countReceipts(c, options)
+  // Match the receipt-driven page path and avoid scanning unindexed
+  // `txs.fee_payer` values when counting.
+  if (options.status !== undefined || options.feePayer !== undefined)
+    return Receipts.countReceipts(c, options)
 
   const { address, chainId } = options
   const store = c.get('store')
@@ -1373,8 +1377,8 @@ export declare namespace scanTransactions {
 
 /**
  * The `txs` columns {@link toRpcTransaction} reconstructs a transaction from.
- * Shared by the list scan and the receipt-driven `status` path so the two
- * queries cannot drift from the reconstruction.
+ * Shared by the list scan and receipt-driven paths so the queries cannot drift
+ * from the reconstruction.
  */
 const transactionColumns = `block_num, block_timestamp, idx, hash, type, "from", "to", value, input,
                    gas_limit, max_fee_per_gas, max_priority_fee_per_gas,
@@ -1396,6 +1400,7 @@ function toRpcTransaction(row: Record<string, unknown>) {
     blockHash: null,
     blockNumber: Value.toHex(row['block_num']) ?? null,
     blockTimestamp: timestamp ? Value.toHex(Math.floor(Date.parse(timestamp) / 1000)) : undefined,
+    feePayer: typeof row['fee_payer'] === 'string' ? row['fee_payer'] : undefined,
     feeToken: typeof row['fee_token'] === 'string' ? row['fee_token'] : undefined,
     from: row['from'],
     gas: Value.toHex(row['gas_limit']),