tapimo 0.5.2 → 0.6.0

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

@@ -14,14 +14,13 @@ 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 FxOracle from '../FxOracle.js'
 import * as Tokens from './tokens.js'
+import * as Transactions from './transactions.js'
+import * as Valuation from './valuation.js'
 
-// Receipts and transactions deliberately form an import cycle (receipts reuses
-// the transaction-type decoder and fee-token embedder; transactions embeds
-// receipts). Neither module may touch the other's exports during module
-// evaluation: schema references across the cycle must stay inside `z.lazy`, and
-// function references are call-time only.
-import { decodeTransactionType, embedFeeTokens, schema as txSchema } from './transactions.js'
+// Receipts and transactions import each other. Cross-module schemas stay lazy,
+// while function references resolve at call time.
 
 /** Example transaction hash surfaced in OpenAPI docs. */
 const exampleHash = '0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'
@@ -33,7 +32,7 @@ const exampleHash = '0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298
  */
 function computeFeeAmount(gasUsed: number | undefined, effectiveGasPrice: string | undefined) {
   if (gasUsed === undefined || effectiveGasPrice === undefined) return undefined
-  return Fees.fromGas(BigInt(gasUsed), BigInt(effectiveGasPrice)).toString()
+  return Fees.fromGas(BigInt(gasUsed), BigInt(effectiveGasPrice))
 }
 
 /** Zod schemas owned by the receipt handlers. */
@@ -187,28 +186,39 @@ export namespace schema {
       .check(z.describe('The transaction receipt exactly as returned by JSON-RPC.'))
   }
 
-  /**
-   * Metadata for a receipt: the verbatim JSON-RPC receipt (always present) plus
-   * resources embedded on demand via `include`.
-   */
+  /** Receipt metadata containing valuation provenance and the verbatim JSON-RPC receipt. */
   export const ReceiptMeta = z
     .object({
-      feeToken: z
-        .optional(z.lazy(() => Tokens.schema.getToken.Response))
-        .check(z.describe('Fee-token details included only when you request `include=feeToken`.')),
+      pricing: z
+        .optional(Valuation.schema.Pricing)
+        .check(
+          z.describe(
+            'Rate provenance for the fee valuation. Present when conversion rates were consulted.',
+          ),
+        ),
       rpc: Rpc.Receipt.check(z.describe('The original JSON-RPC receipt payload.')),
     })
+    .check(z.describe('Metadata for this receipt, including pricing and the JSON-RPC payload.'))
+
+  /** The fee charged to the fee payer, carrying its value in the requested denomination. */
+  export const FeeAmount = z
+    .extend(Schema.TokenAmount, {
+      valuation: z
+        .optional(z.nullable(Valuation.schema.Value))
+        .check(
+          z.describe(
+            'The fee’s nominal value in the requested `denomination`. `null` when rates were unavailable.',
+          ),
+        ),
+    })
     .check(
-      z.describe(
-        'Metadata for this receipt: the original JSON-RPC payload plus any requested `include` resources.',
-      ),
+      z.describe('The fee charged to the fee payer, with its value in the requested denomination.'),
     )
 
   /**
    * A humanized transaction receipt: decoded `status`/`type`, plain-number gas
-   * and block fields, and decimal-string fee/price values. The raw event logs
-   * are surfaced verbatim under `logs`, and the full JSON-RPC receipt under
-   * `meta.rpc`.
+   * and block fields, a structured fee amount, and a decimal-string gas price.
+   * The raw event logs are surfaced under `logs`, and the RPC receipt under `meta.rpc`.
    */
   export const Receipt = z
     .object({
@@ -245,19 +255,15 @@ export namespace schema {
       effectiveGasPrice: Schema.DecimalString.check(
         z.describe('Effective gas price paid for this transaction, in attodollars per gas.'),
       ),
-      feeAmount: Schema.DecimalString.check(
-        z.describe(
-          'Fee charged to the fee payer, as a decimal integer string in the fee token’s base units.',
-        ),
-      ),
+      feeAmount: FeeAmount.check(z.describe('Fee charged to the fee payer, denominated in USD.')),
       feePayer: z
         .optional(Schema.Address)
         .check(z.describe('The address that paid the transaction fee.')),
       feeToken: z
-        .optional(Schema.Address)
+        .optional(z.lazy(() => Tokens.schema.TokenReference))
         .check(
           z.describe(
-            'The token used to pay the fee; on Tempo this is a USD stablecoin such as `pathUSD`.',
+            'The token used to pay the fee, with RPC metadata and optional curated fields.',
           ),
         ),
       gasUsed: z
@@ -277,7 +283,7 @@ export namespace schema {
           z.describe('Event logs emitted by this transaction, returned in JSON-RPC log format.'),
         ),
       meta: ReceiptMeta.check(
-        z.describe('The original JSON-RPC payload plus any resources requested with `include`.'),
+        z.describe('Receipt metadata containing pricing provenance and the JSON-RPC payload.'),
       ),
       recipient: z
         .nullable(Schema.Address)
@@ -312,7 +318,9 @@ export namespace schema {
           z.describe('The transaction position within its block.'),
           z.meta({ examples: [0] }),
         ),
-      type: z.lazy(() => txSchema.TransactionType).check(z.meta({ examples: ['eip1559'] })),
+      type: z
+        .lazy(() => Transactions.schema.TransactionType)
+        .check(z.meta({ examples: ['eip1559'] })),
     })
     .check(
       z.describe(
@@ -334,25 +342,25 @@ export namespace schema {
       })
       .check(z.describe('Path parameters used to look up a receipt by transaction hash.'))
 
-    /** Optional related resource that callers opt into via `include`. */
+    /** Optional curated token fields that callers opt into via `include`. */
     export const Include = z
-      .enum(['feeToken'])
-      .check(z.describe('Related resource you can opt into with the `include` query parameter.'))
+      .enum(['feeToken.logoUri', 'feeToken.verified'])
+      .check(z.describe('Additional fee-token fields you can request with `include`.'))
 
     /**
      * Parses a comma-separated `include` query value into a list of optional
-     * resources to embed. Extra lookups (e.g. fee-token metadata) only run when
-     * explicitly requested, keeping the base receipt response fast.
+     * token fields to embed. Curated lookups only run when explicitly requested.
      */
     export const includeQuery = Schema.includeQuery(
       Include,
-      'Comma-separated related resources to include, such as `feeToken`.',
+      'Comma-separated fee-token fields to include, such as `feeToken.logoUri,feeToken.verified`.',
     )
 
     /** Query parameters for receipt requests. */
     export const Query = z
       .strictObject({
         chainId: Schema.ChainIdQuery,
+        denomination: Schema.Denomination,
         include: includeQuery,
       })
       .check(z.describe('Query parameters for looking up a receipt.'))
@@ -363,13 +371,9 @@ export namespace schema {
 
   /** Schemas for the getReceipts (list) operation. */
   export namespace getReceipts {
-    /**
-     * Optional resources for the receipt list: the per-row `feeToken` embed
-     * plus the response-wide capped `totalCount`. The detail route keeps its
-     * own `feeToken`-only {@link getReceipt.Include}.
-     */
+    /** Optional fee-token fields and response-wide count metadata. */
     export const Include = z
-      .enum(['feeToken', 'totalCount'])
+      .enum(['feeToken.logoUri', 'feeToken.verified', 'totalCount'])
       .check(
         z.describe('Related resources to include in each receipt row or in response metadata.'),
       )
@@ -377,7 +381,7 @@ export namespace schema {
     /** Parses the comma-separated `include` value for the receipt list. */
     export const includeQuery = Schema.includeQuery(
       Include,
-      'Comma-separated related resources to include, such as `feeToken,totalCount`.',
+      'Comma-separated resources to include, such as `feeToken.logoUri,feeToken.verified,totalCount`.',
     )
 
     /** Query parameters for receipt list requests. */
@@ -394,6 +398,7 @@ export namespace schema {
         'blockNumber.to': Schema.blockNumberBound('receipts', 'to'),
         chainId: Schema.ChainIdQuery,
         cursor: Schema.Cursor,
+        denomination: Schema.Denomination,
         feePayer: z
           .optional(Schema.Address)
           .check(z.describe('Filter to receipts whose transaction fee was paid by this address.')),
@@ -430,14 +435,28 @@ export namespace schema {
      * which stores neither the block hash nor the event logs, so those fields are
      * `null`/empty in the list `meta.rpc` payload.
      */
+    /** Page-level resources: opt-in counts plus valuation rate provenance. */
+    export const Meta = z
+      .object({
+        pricing: z
+          .optional(Valuation.schema.Pricing)
+          .check(
+            z.describe(
+              'Rate provenance for fee valuations. Present when conversion rates were ' +
+                'consulted; absent when every value was identity-valued or rates were unavailable.',
+            ),
+          ),
+        totalCount: z.optional(Schema.TotalCount),
+        totalCountCapped: z.optional(Schema.TotalCountCapped),
+      })
+      .check(z.describe('Page-level resources attached to this response.'))
+
     export const Response = z
       .object({
         data: z.array(getReceipt.Response).check(z.describe('Receipts on this page.')),
         meta: z
-          .optional(Schema.CountMeta)
-          .check(
-            z.describe('Response-level metadata requested with `include`, such as `totalCount`.'),
-          ),
+          .optional(Meta)
+          .check(z.describe('Page-level resources: opt-in counts and valuation rate provenance.')),
         nextCursor: Schema.NextCursor,
       })
       .check(z.describe('A page of receipts ordered by block number and transaction position.'))
@@ -445,7 +464,8 @@ export namespace schema {
 }
 
 /** Creates receipt handlers. */
-export function receipts() {
+export function receipts(options: receipts.Options = {}) {
+  const oracle = options.fx?.oracle ?? FxOracle.ecb()
   return new Hono<App.Environment>()
     .get(
       '/v1/transactions/receipts',
@@ -459,7 +479,7 @@ export function receipts() {
           'List transaction receipts across Tempo, with filters for addresses, blocks, timestamps, fees, and status.',
         operationId: 'getReceipts',
         responses: OpenApi.responses({
-          errors: { 502: 'Could not read indexed receipt data from TIDX.' },
+          errors: { 502: 'Could not read receipt or token data from an upstream service.' },
           success: {
             description: 'A page of transaction receipts.',
             schema: schema.getReceipts.Response,
@@ -484,9 +504,8 @@ export function receipts() {
         const query = c.req.valid('query')
         const chainId = query.chainId ?? c.get('chainId')
 
-        // Cursor pages are anchored below the head and effectively immutable, so
-        // cache them longer; the head page keeps the route's short `feed` default.
-        if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+        // Cursor pages carry current fee valuations and curated verification data.
+        if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.metadata)
 
         try {
           // `totalCount` is opt-in and shares the page's filters; run it
@@ -516,7 +535,10 @@ export function receipts() {
             feeToken: query.feeToken,
             fromBlock: query['blockNumber.from'],
             fromTimestamp: query['timestamp.from'],
-            include: query.include.includes('feeToken') ? ['feeToken'] : [],
+            include: query.include.filter(
+              (resource): resource is z.output<typeof schema.getReceipt.Include> =>
+                resource !== 'totalCount',
+            ),
             limit: query.limit,
             order: query.order,
             page: query.page,
@@ -527,15 +549,43 @@ export function receipts() {
             toTimestamp: query['timestamp.to'],
           })
 
-          const meta = countPromise ? await countPromise : undefined
+          // Value each fee via its own currency tag, in the requested
+          // denomination.
+          const denomination = query.denomination ?? 'USD'
+          const rates = await Valuation.ratesFor(c, {
+            currencies: receipts.data.map((receipt) => receipt.feeAmount.currency),
+            denomination,
+            oracle,
+          })
+          const data = receipts.data.map((receipt) => ({
+            ...receipt,
+            feeAmount: {
+              ...receipt.feeAmount,
+              valuation: Valuation.valuationFor({
+                amount: BigInt(receipt.feeAmount.baseUnits),
+                denomination,
+                rates,
+                token: receipt.feeAmount,
+              }),
+            },
+          }))
+
+          const counts = countPromise ? await countPromise : undefined
+          const meta = {
+            ...(rates ? { pricing: Valuation.pricing(rates, oracle) } : {}),
+            ...counts,
+          }
           return c.json(
             Response.validated(schema.getReceipts.Response, {
-              ...receipts,
-              ...(meta ? { meta } : {}),
+              data,
+              ...(Object.keys(meta).length > 0 ? { meta } : {}),
+              nextCursor: receipts.nextCursor,
             }),
             200,
           )
         } catch (cause) {
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
           return Response.upstream(c, cause)
         }
       },
@@ -560,7 +610,7 @@ export function receipts() {
               description: 'No receipt was found for that transaction hash.',
               codes: ['receipt_not_found'],
             },
-            502: 'Could not read receipt data from the upstream JSON-RPC node.',
+            502: 'Could not read receipt or token data from upstream JSON-RPC.',
           },
           success: {
             description: 'A single transaction receipt with status, gas, fees, and logs.',
@@ -571,11 +621,8 @@ export function receipts() {
         tags: ['Transactions'],
       }),
       Cache.response<App.Environment>({
-        // A receipt exists only once the transaction is mined: the lookup is
-        // either a 404 (unknown / not-yet-mined hash) or a final 200, never a
-        // pending 200. Default to no-store so the 404 isn't cached with a
-        // long-lived header (which would mask the receipt once mined); the handler
-        // unconditionally upgrades the 200 to `immutable` below.
+        // Default to no-store so a 404 does not mask the eventual mined receipt.
+        // Successful responses use the metadata policy for current valuations.
         cacheControl: Cache.policies.noStore,
         name: 'tempo-api:receipts:v1',
         key: (c) => Cache.urlKey(c, schema.getReceipt.Query),
@@ -619,50 +666,73 @@ export function receipts() {
 
           const data = humanizeReceipt(Response.validated(schema.Rpc.Receipt, rpc))
 
-          // A receipt is only returned once the transaction is mined, so it is
-          // immutable and can be cached aggressively.
-          Cache.setPolicy(c, Cache.policies.immutable)
+          // Mined receipts still carry current valuations and verification data.
+          Cache.setPolicy(c, Cache.policies.metadata)
 
-          // Fee-token metadata is opt-in: resolving it is an extra lookup, so it
-          // only runs when requested via `include=feeToken` and the receipt
-          // declares a fee token.
-          const feeToken = data.feeToken
-          if (!query.include.includes('feeToken') || feeToken === undefined)
-            return c.json(Response.validated(schema.getReceipt.Response, data), 200)
+          const [enriched] = await enrichReceipts(c, {
+            chainId,
+            include: query.include,
+            receipts: [data],
+          })
+          if (!enriched) throw new Error('Unable to enrich transaction receipt')
 
-          const token = await Timing.time(c, 'fee_token', () =>
-            Tokens.resolveToken(c, { address: feeToken, chainId }).catch(() => undefined),
-          )
-          return c.json(
-            Response.validated(
-              schema.getReceipt.Response,
-              token ? { ...data, meta: { ...data.meta, feeToken: token } } : data,
-            ),
-            200,
-          )
+          // Value the fee via its own currency tag, in the requested
+          // denomination.
+          const denomination = query.denomination ?? 'USD'
+          const rates = await Valuation.ratesFor(c, {
+            currencies: [enriched.feeAmount.currency],
+            denomination,
+            oracle,
+          })
+          const valued = {
+            ...enriched,
+            feeAmount: {
+              ...enriched.feeAmount,
+              valuation: Valuation.valuationFor({
+                amount: BigInt(enriched.feeAmount.baseUnits),
+                denomination,
+                rates,
+                token: enriched.feeAmount,
+              }),
+            },
+            meta: {
+              ...enriched.meta,
+              ...(rates ? { pricing: Valuation.pricing(rates, oracle) } : {}),
+            },
+          }
+          return c.json(Response.validated(schema.getReceipt.Response, valued), 200)
         } catch (cause) {
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
           return Response.upstream(c, cause)
         }
       },
     )
 }
 
+export declare namespace receipts {
+  /** Options for the receipt handlers. */
+  type Options = {
+    /** FX configuration backing fee valuation. */
+    fx?: Valuation.addresses.Fx | undefined
+  }
+}
+
 /**
- * Lists humanized receipts and embeds opt-in `include` resources (currently
- * `feeToken`).
+ * Lists humanized receipts with required fee-token metadata and optional curated fields.
  */
 export async function listReceipts(c: Context<App.Environment>, options: listReceipts.Options) {
   const { include, ...rest } = options
   const page = await getReceipts(c, rest)
-  const data = include.includes('feeToken')
-    ? await embedFeeTokens(c, page.data, rest.chainId)
-    : page.data
-  return { ...page, data }
+  return {
+    ...page,
+    data: await enrichReceipts(c, { chainId: rest.chainId, include, receipts: page.data }),
+  }
 }
 
 export declare namespace listReceipts {
   type Options = getReceipts.Options & {
-    /** Optional related resources to embed (e.g. `feeToken`). */
+    /** Optional curated fee-token fields to embed. */
     include: readonly z.output<typeof schema.getReceipt.Include>[]
   }
 }
@@ -825,7 +895,7 @@ export function getReceipts(c: Context<App.Environment>, options: getReceipts.Op
         // Reconstruct the RPC shape from the indexed columns, then humanize it
         // through the same path as the detail endpoint so the list and detail
         // responses are identical. Rows that fail to reconstruct are skipped.
-        const data: z.output<typeof schema.Receipt>[] = []
+        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 }
@@ -977,8 +1047,8 @@ export async function embedReceipts(
   c: Context<App.Environment>,
   options: embedReceipts.Options,
 ): Promise<Map<string, z.output<typeof schema.Receipt>>> {
-  const { chainId, rows } = options
-  const found = new Map<string, z.output<typeof schema.Receipt>>()
+  const { chainId, include, rows } = options
+  const found = new Map<string, humanizeReceipt.Output>()
 
   // Only mined rows can have a receipt; their block numbers also feed the
   // block bound the `logs` lookup requires.
@@ -989,7 +1059,7 @@ export async function embedReceipts(
     blocks.push(row.blockNumber)
     hashes.add(row.hash.toLowerCase())
   }
-  if (hashes.size === 0) return found
+  if (hashes.size === 0) return new Map()
 
   const tidx = c.get('getTidx')(chainId)
   const inList = [...hashes].map((hash) => `'${hash}'`).join(', ')
@@ -1057,7 +1127,8 @@ export async function embedReceipts(
         meta: { ...receipt.meta, rpc: { ...receipt.meta.rpc, logs } },
       })
     }
-    return found
+    const receipts = await enrichReceipts(c, { chainId, include, receipts: [...found.values()] })
+    return new Map(receipts.map((receipt) => [receipt.transactionHash.toLowerCase(), receipt]))
   }
 
   const receiptRowByHash = new Map<string, Record<string, unknown>>()
@@ -1087,7 +1158,8 @@ export async function embedReceipts(
     })
     if (rpc.success) found.set(hash, humanizeReceipt(rpc.data))
   }
-  return found
+  const receipts = await enrichReceipts(c, { chainId, include, receipts: [...found.values()] })
+  return new Map(receipts.map((receipt) => [receipt.transactionHash.toLowerCase(), receipt]))
 }
 
 export declare namespace embedReceipts {
@@ -1095,12 +1167,14 @@ export declare namespace embedReceipts {
   type Options = {
     /** Target chain id. */
     chainId: z.output<typeof Schema.ChainId>
+    /** Optional curated fee-token fields to embed. */
+    include: readonly string[]
     /**
      * Pre-fetched humanized receipts for the page (the `status`-filtered
      * transactions path). When provided, the receipts query is skipped and only
      * the page's event logs are fetched and reattached.
      */
-    receipts?: readonly z.output<typeof schema.Receipt>[] | undefined
+    receipts?: readonly humanizeReceipt.Output[] | undefined
     /**
      * The page's humanized transaction rows. Typed structurally (rather than as
      * the transactions schema output) so this module never touches the
@@ -1119,18 +1193,37 @@ export declare namespace embedReceipts {
   }
 }
 
+/** Resolves required RPC fee-token metadata and optional curated fields for receipts. */
+export function enrichReceipts(c: Context<App.Environment>, options: enrichReceipts.Options) {
+  return Transactions.enrichFeeTokens(c, {
+    chainId: options.chainId,
+    include: options.include,
+    rows: options.receipts,
+  })
+}
+
+export declare namespace enrichReceipts {
+  /** Inputs for enriching humanized receipts. */
+  type Options = {
+    /** Target chain id. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** Optional curated fee-token fields to embed. */
+    include: readonly string[]
+    /** Humanized receipts whose fee token is still an address. */
+    receipts: readonly humanizeReceipt.Output[]
+  }
+}
+
 /**
  * Humanizes a JSON-RPC transaction receipt: decodes `status`/`type`, converts
- * hex quantities to decimal strings and block fields to numbers, and derives the
+ * gas price and fee values, converts block fields to numbers, and derives the
  * block `timestamp` from the top-level `blockTimestamp` (present when
  * reconstructed from the index) or the (shared) per-log timestamp — `null` when
  * neither is available. The verbatim payload is preserved under `meta.rpc` and
  * the raw logs under `logs`. Shared by the receipt detail (RPC source) and list
  * (reconstructed from the indexer) endpoints, so both expose an identical shape.
  */
-export function humanizeReceipt(
-  rpc: z.output<typeof schema.Rpc.Receipt>,
-): z.output<typeof schema.Receipt> {
+export function humanizeReceipt(rpc: z.output<typeof schema.Rpc.Receipt>): humanizeReceipt.Output {
   const gasUsed = Value.hexToNumber(rpc.gasUsed) ?? 0
   const effectiveGasPrice = Value.fromHex(rpc.effectiveGasPrice) ?? '0'
   return {
@@ -1139,7 +1232,11 @@ export function humanizeReceipt(
     contractAddress: rpc.contractAddress ?? null,
     cumulativeGasUsed: Value.hexToNumber(rpc.cumulativeGasUsed) ?? 0,
     effectiveGasPrice,
-    feeAmount: computeFeeAmount(gasUsed, effectiveGasPrice) ?? '0',
+    feeAmount: Value.tokenAmount({
+      baseUnits: computeFeeAmount(gasUsed, effectiveGasPrice) ?? 0n,
+      currency: 'USD',
+      decimals: Fees.tokenDecimals,
+    }),
     feePayer: rpc.feePayer ?? undefined,
     feeToken: rpc.feeToken ?? undefined,
     gasUsed,
@@ -1152,7 +1249,15 @@ export function humanizeReceipt(
     timestamp: Value.hexSecondsToIso(rpc.blockTimestamp ?? rpc.logs[0]?.blockTimestamp) ?? null,
     transactionHash: rpc.transactionHash,
     transactionIndex: Value.hexToNumber(rpc.transactionIndex) ?? 0,
-    type: decodeTransactionType(rpc.type),
+    type: Transactions.decodeTransactionType(rpc.type),
+  }
+}
+
+export declare namespace humanizeReceipt {
+  /** Humanized receipt before its fee-token address is resolved to metadata. */
+  type Output = Omit<z.output<typeof schema.Receipt>, 'feeToken'> & {
+    /** Address of the token used to pay the fee. */
+    feeToken?: z.output<typeof Schema.Address> | undefined
   }
 }
 

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

@@ -980,6 +980,27 @@ describe('GET /tokens/:symbol', () => {
 })
 
 describe('GET /tokens/:token/transactions', () => {
+  test('parses granular fee-token includes', () => {
+    expect(
+      Tokens.schema.getTokenTransactions.Query.parse({
+        include: 'feeToken.logoUri,feeToken.verified,token,totalCount',
+      }).include,
+    ).toMatchInlineSnapshot(`
+      [
+        "feeToken.logoUri",
+        "feeToken.verified",
+        "token",
+        "totalCount",
+      ]
+    `)
+    expect(
+      Tokens.schema.getTokenTransactions.Query.safeParse({ include: 'feeToken' }).success,
+    ).toBe(false)
+    expect(
+      Tokens.schema.getTokenTransactions.Query.safeParse({ include: 'token.logoUri' }).success,
+    ).toBe(false)
+  })
+
   test('returns a transaction page touching the token contract', async () => {
     const client = app()
     const response = await client.v1.tokens[':token'].transactions.$get(
@@ -996,6 +1017,12 @@ describe('GET /tokens/:token/transactions', () => {
     for (const tx of body.data) {
       const involves = tx.sender === TestApp.token || tx.recipient === TestApp.token
       expect(involves).toBe(true)
+      if (tx.feeToken) {
+        expect(tx.feeToken.address).toBe(tx.meta.rpc.feeToken)
+        expect(typeof tx.feeToken.symbol).toBe('string')
+        expect(tx.feeToken.logoUri).toBeUndefined()
+        expect(tx.feeToken.verified).toBeUndefined()
+      }
     }
     // Default ordering is newest-first (descending block then in-block index).
     const blocks = body.data
@@ -1006,6 +1033,22 @@ describe('GET /tokens/:token/transactions', () => {
     expect(body.meta).toBeUndefined()
   })
 
+  test('includes requested fee-token fields', async () => {
+    const client = app()
+    const response = await client.v1.tokens[':token'].transactions.$get(
+      {
+        param: { token: TestApp.token },
+        query: { include: 'feeToken.logoUri,feeToken.verified', limit: '5' },
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Tokens.schema.getTokenTransactions.Response)
+
+    expect(response.status).toBe(200)
+    const withFeeToken = body.data.find((transaction) => transaction.feeToken)
+    if (withFeeToken) expect(typeof withFeeToken.feeToken!.verified).toBe('boolean')
+  })
+
   test('embeds a capped total count on demand via include=totalCount', async () => {
     const client = app()
     const response = await client.v1.tokens[':token'].transactions.$get(