tapimo 0.5.2 → 0.6.0

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

@@ -239,6 +239,12 @@ export namespace schema {
     'A compact TIP-20 token reference with identity and display fields only.',
   )
 
+  /** RPC token metadata embedded in resources, with optional curated fields. */
+  export const TokenReference = Schema.describe(
+    z.partial(z.omit(Token, { id: true }), { logoUri: true, verified: true }),
+    'A compact TIP-20 token reference with RPC metadata and optional enrichments.',
+  )
+
   /** Schemas for the getTokenBySymbol operation. */
   export namespace getTokenBySymbol {
     /** Hono route pattern for verified token symbols. */
@@ -458,9 +464,9 @@ export namespace schema {
       })
       .check(z.describe('Path parameters for listing transactions involving this token contract.'))
 
-    /** Optional related resources that callers opt into via `include`. */
+    /** Optional scoped-token resources and fee-token fields requested via `include`. */
     export const Include = z
-      .enum(['feeToken', 'token', 'totalCount'])
+      .enum(['feeToken.logoUri', 'feeToken.verified', 'token', 'totalCount'])
       .check(z.describe('Related resources to include only when you request them with `include`.'))
 
     /**
@@ -470,7 +476,7 @@ export namespace schema {
      */
     export const includeQuery = Schema.includeQuery(
       Include,
-      'Comma-separated related resources to include, such as `feeToken,token,totalCount`.',
+      'Comma-separated related resources to include, such as `feeToken.logoUri,feeToken.verified,token,totalCount`.',
     )
 
     /** Query parameters for token transaction requests. */
@@ -974,17 +980,22 @@ export function tokens() {
         const { token: address } = c.req.valid('param')
         const query = c.req.valid('query')
 
-        // Cursor pages are anchored below the head and effectively immutable,
-        // so cache them aggressively; the head page keeps the `feed` default.
-        if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+        // Cursor pages are anchored below the head. Cache chain data as immutable,
+        // but refresh requested token metadata on the metadata schedule.
+        if (query.cursor !== undefined)
+          Cache.setPolicy(
+            c,
+            query.include.some(
+              (resource) => resource === 'token' || resource.startsWith('feeToken.'),
+            )
+              ? Cache.policies.metadata
+              : Cache.policies.immutable,
+          )
 
         try {
           const chainId = query.chainId ?? c.get('chainId')
-          // Resolve the transaction page and (opt-in) token metadata
-          // concurrently so the token lookup is hidden behind the
-          // transaction query rather than adding to it. The `feeToken`
-          // include flows through to `listTransactions` for per-row embeds;
-          // `token` is a root-level embed for the token being scoped to.
+          // Resolve the transaction page and scoped token concurrently so the
+          // token lookup is hidden behind the transaction query.
           const includeToken = query.include.includes('token')
           // `totalCount` is opt-in; count transactions touching this token
           // (address-scoped to the contract) under the same filters as the
@@ -1010,7 +1021,10 @@ export function tokens() {
               feeToken: query.feeToken,
               fromBlock: query['blockNumber.from'],
               fromTimestamp: query['timestamp.from'],
-              include: query.include.includes('feeToken') ? ['feeToken'] : [],
+              include: query.include.filter(
+                (resource): resource is 'feeToken.logoUri' | 'feeToken.verified' =>
+                  resource === 'feeToken.logoUri' || resource === 'feeToken.verified',
+              ),
               limit: query.limit,
               order: query.order,
               page: query.page,
@@ -1176,6 +1190,7 @@ export function getTokenMetadata(c: Context<App.Environment>, options: getTokenM
 
   return Store.memoize(
     async () => {
+      // TODO(viem): Flatten concurrent metadata multicalls before encoding aggregate3 calldata.
       const fresh = await getClient(chainId).token.getMetadata({ token: address as Address })
       return {
         currency: fresh.currency,

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

@@ -21,7 +21,27 @@ beforeAll(async () => {
 })
 
 describe('GET /transactions/:transactionHash', () => {
-  test('humanizes the transaction, keeps the raw RPC under `meta.rpc`, and embeds the fee token on demand', async () => {
+  test('parses granular fee-token includes', () => {
+    expect(
+      Transactions.schema.getTransaction.Query.parse({
+        include: 'feeToken.logoUri,feeToken.verified,receipt',
+      }).include,
+    ).toMatchInlineSnapshot(`
+      [
+        "feeToken.logoUri",
+        "feeToken.verified",
+        "receipt",
+      ]
+    `)
+    expect(
+      Transactions.schema.getTransaction.Query.safeParse({ include: 'feeToken' }).success,
+    ).toBe(false)
+    expect(
+      Transactions.schema.getTransaction.Query.safeParse({ include: 'token.logoUri' }).success,
+    ).toBe(false)
+  })
+
+  test('humanizes the transaction and resolves its fee token', async () => {
     if (!transactionHash) {
       console.warn('[live-rpc] no recent transaction found; skipping transaction happy path')
       return
@@ -51,12 +71,24 @@ describe('GET /transactions/:transactionHash', () => {
     // transaction; they live on `/transactions/:transactionHash/receipt` instead.
     expect('status' in body).toBe(false)
     expect('gasUsed' in body).toBe(false)
-    // Fee-token metadata is opt-in: the base response must not embed it.
-    expect(body.meta.feeToken).toBeUndefined()
+    if (body.feeToken) {
+      expect(body.feeToken.address).toBe(body.meta.rpc.feeToken)
+      expect(typeof body.feeToken.currency).toBe('string')
+      expect(Number.isInteger(body.feeToken.decimals)).toBe(true)
+      expect(typeof body.feeToken.name).toBe('string')
+      expect(typeof body.feeToken.symbol).toBe('string')
+      expect(body.feeToken.logoUri).toBeUndefined()
+      expect(body.feeToken.verified).toBeUndefined()
+      expect(body.feeToken).not.toHaveProperty('amount')
+      expect(body.feeToken).not.toHaveProperty('id')
+    }
 
-    // include=feeToken: resolved metadata is embedded under meta (best-effort).
+    // Curated fields are independently opt-in on the fee-token reference.
     const includedResponse = await client.v1.transactions[':transactionHash'].$get(
-      { param: { transactionHash: transactionHash }, query: { include: 'feeToken' } },
+      {
+        param: { transactionHash: transactionHash },
+        query: { include: 'feeToken.logoUri,feeToken.verified' },
+      },
       TestApp.auth,
     )
     const includedBody = await TestApp.json(
@@ -65,12 +97,8 @@ describe('GET /transactions/:transactionHash', () => {
     )
     expect(includedResponse.status).toBe(200)
     if (includedBody.feeToken) {
-      expect(includedBody.feeToken).toMatch(/^0x[0-9a-f]{40}$/)
-      // When metadata resolves, it must describe the fee token itself.
-      if (includedBody.meta?.feeToken) {
-        expect(includedBody.meta.feeToken.address).toBe(includedBody.feeToken)
-        expect(typeof includedBody.meta.feeToken.symbol).toBe('string')
-      }
+      expect(includedBody.feeToken.address).toBe(includedBody.meta.rpc.feeToken)
+      expect(typeof includedBody.feeToken.verified).toBe('boolean')
     }
   })
 
@@ -132,7 +160,28 @@ describe('GET /transactions/:transactionHash', () => {
 })
 
 describe('GET /transactions', () => {
-  test('returns a humanized transaction page, embedding fee tokens on demand', async () => {
+  test('parses granular fee-token and list includes', () => {
+    expect(
+      Transactions.schema.getTransactions.Query.parse({
+        include: 'feeToken.logoUri,feeToken.verified,receipt,totalCount',
+      }).include,
+    ).toMatchInlineSnapshot(`
+      [
+        "feeToken.logoUri",
+        "feeToken.verified",
+        "receipt",
+        "totalCount",
+      ]
+    `)
+    expect(
+      Transactions.schema.getTransactions.Query.safeParse({ include: 'feeToken' }).success,
+    ).toBe(false)
+    expect(
+      Transactions.schema.getTransactions.Query.safeParse({ include: 'token.verified' }).success,
+    ).toBe(false)
+  })
+
+  test('returns a humanized transaction page with fee-token references', async () => {
     const client = TestApp.client()
     const response = await client.v1.transactions.$get({ query: { limit: '5' } }, TestApp.auth)
     const body = await TestApp.json(response, Transactions.schema.getTransactions.Response)
@@ -169,13 +218,18 @@ describe('GET /transactions', () => {
       expect(typeof transaction!.nonce).toBe('number')
       expect(transaction!.meta.rpc.type).toMatch(/^0x[0-9a-f]+$/)
       // Receipt-derived fields are not on the list payload, matching the detail
-      // endpoint; fee-token metadata is opt-in.
+      // endpoint; fee-token core metadata is included by default.
       expect('status' in transaction!).toBe(false)
-      expect(transaction!.meta.feeToken).toBeUndefined()
+      if (transaction!.feeToken) {
+        expect(transaction!.feeToken.address).toBe(transaction!.meta.rpc.feeToken)
+        expect(typeof transaction!.feeToken.symbol).toBe('string')
+        expect(transaction!.feeToken.logoUri).toBeUndefined()
+        expect(transaction!.feeToken.verified).toBeUndefined()
+      }
     }
 
     const includedResponse = await client.v1.transactions.$get(
-      { query: { limit: '5', include: 'feeToken' } },
+      { query: { limit: '5', include: 'feeToken.logoUri,feeToken.verified' } },
       TestApp.auth,
     )
     const includedBody = await TestApp.json(
@@ -183,11 +237,10 @@ describe('GET /transactions', () => {
       Transactions.schema.getTransactions.Response,
     )
     expect(includedResponse.status).toBe(200)
-    const withFeeToken = includedBody.data.find((transaction) => transaction.meta?.feeToken)
+    const withFeeToken = includedBody.data.find((transaction) => transaction.feeToken)
     if (withFeeToken) {
-      // When metadata resolves, it must describe the transaction's fee token.
-      expect(withFeeToken.meta.feeToken!.address).toBe(withFeeToken.feeToken)
-      expect(typeof withFeeToken.meta.feeToken!.symbol).toBe('string')
+      expect(withFeeToken.feeToken!.address).toBe(withFeeToken.meta.rpc.feeToken)
+      expect(typeof withFeeToken.feeToken!.verified).toBe('boolean')
     }
   })
 

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

@@ -286,20 +286,9 @@ export namespace schema {
       .check(z.describe('The transaction exactly as returned by JSON-RPC.'))
   }
 
-  /**
-   * Metadata for a transaction: the verbatim JSON-RPC transaction (always
-   * present) plus resources embedded on demand via `include`.
-   *
-   * The `feeToken` and `receipt` schemas are wrapped in `z.lazy` because
-   * `tokens.ts`/`receipts.ts` and `transactions.ts` mutually reference each
-   * other's schemas; deferring these lookups avoids the import-cycle crash
-   * during module init.
-   */
+  /** Transaction metadata with the raw RPC transaction and optional receipt. */
   export const TransactionMeta = z
     .object({
-      feeToken: z
-        .optional(z.lazy(() => Tokens.schema.getToken.Response))
-        .check(z.describe('Fee-token details included only when you request `include=feeToken`.')),
       receipt: z
         .optional(z.lazy(() => Receipts.schema.Receipt))
         .check(
@@ -367,10 +356,10 @@ export namespace schema {
           z.meta({ examples: [4217] }),
         ),
       feeToken: z
-        .optional(Schema.Address)
+        .optional(z.lazy(() => Tokens.schema.TokenReference))
         .check(
           z.describe(
-            'The fee token requested by the transaction; Tempo fees are paid in USD stablecoins such as `pathUSD`.',
+            'The token requested for transaction fees, with RPC metadata and optional curated fields.',
           ),
         ),
       gas: z
@@ -484,20 +473,19 @@ export namespace schema {
       })
       .check(z.describe('Path parameters used to look up a transaction.'))
 
-    /** Optional related resource that callers opt into via `include`. */
+    /** Optional receipt and fee-token fields that callers opt into via `include`. */
     export const Include = z
-      .enum(['feeToken', 'receipt'])
-      .check(z.describe('Related resource you can opt into with the `include` query parameter.'))
+      .enum(['feeToken.logoUri', 'feeToken.verified', 'receipt'])
+      .check(z.describe('Related resources you can request with the `include` query parameter.'))
 
     /**
      * Parses a comma-separated `include` query value into a list of optional
-     * resources to embed. Extra lookups (e.g. fee-token metadata, the receipt)
-     * only run when explicitly requested, keeping the base transaction response
-     * fast.
+     * resources to embed. Curated fee-token fields and the receipt only run when
+     * explicitly requested.
      */
     export const includeQuery = Schema.includeQuery(
       Include,
-      'Comma-separated related resources to include, such as `feeToken,receipt`.',
+      'Comma-separated related resources to include, such as `feeToken.logoUri,feeToken.verified,receipt`.',
     )
 
     /** Query parameters for transaction requests. */
@@ -515,12 +503,11 @@ export namespace schema {
   /** Schemas for the getTransactions (list) operation. */
   export namespace getTransactions {
     /**
-     * Optional resources for the transaction list: the per-row `feeToken` /
-     * `receipt` embeds plus the response-wide capped `totalCount`. The detail
-     * route keeps its own {@link getTransaction.Include}.
+     * Optional resources for transaction rows plus the response-wide capped
+     * `totalCount`. The detail route keeps its own include schema.
      */
     export const Include = z
-      .enum(['feeToken', 'receipt', 'totalCount'])
+      .enum(['feeToken.logoUri', 'feeToken.verified', 'receipt', 'totalCount'])
       .check(
         z.describe('Related resources to include in each transaction row or in response metadata.'),
       )
@@ -528,7 +515,7 @@ export namespace schema {
     /** Parses the comma-separated `include` value for the transaction list. */
     export const includeQuery = Schema.includeQuery(
       Include,
-      'Comma-separated related resources to include, such as `feeToken,receipt,totalCount`.',
+      'Comma-separated related resources to include, such as `feeToken.logoUri,feeToken.verified,receipt,totalCount`.',
     )
 
     /** Query parameters for transaction list requests. */
@@ -606,7 +593,7 @@ export function transactions() {
           'List transactions across Tempo, with filters for addresses, blocks, timestamps, fees, and status.',
         operationId: 'getTransactions',
         responses: OpenApi.responses({
-          errors: { 502: 'Could not read indexed transaction data from TIDX.' },
+          errors: { 502: 'Could not read transaction or token data from an upstream service.' },
           success: {
             description: 'A page of transactions.',
             schema: schema.getTransactions.Response,
@@ -631,10 +618,15 @@ export function transactions() {
         const query = c.req.valid('query')
         const chainId = query.chainId ?? c.get('chainId')
 
-        // A cursor page is anchored below the head, so its contents are
-        // append-only and effectively immutable; cache it aggressively. The head
-        // page (no cursor) keeps the route's short `feed` default.
-        if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+        // Cursor pages are anchored below the head. Cache chain data as immutable,
+        // but refresh requested curated token fields on the metadata schedule.
+        if (query.cursor !== undefined)
+          Cache.setPolicy(
+            c,
+            query.include.some((resource) => resource.startsWith('feeToken.'))
+              ? Cache.policies.metadata
+              : Cache.policies.immutable,
+          )
 
         try {
           // `totalCount` is opt-in and shares the page's filters; run it
@@ -711,7 +703,7 @@ export function transactions() {
               description: 'No transaction was found for that hash.',
               codes: ['transaction_not_found'],
             },
-            502: 'Could not read transaction data from the upstream JSON-RPC node.',
+            502: 'Could not read transaction or token data from upstream JSON-RPC.',
           },
           success: {
             description: 'A single transaction with decoded fields and original JSON-RPC data.',
@@ -769,9 +761,15 @@ export function transactions() {
 
           let data = humanizeTransaction(Response.validated(schema.Rpc.Transaction, rpc))
 
-          // A mined transaction is immutable, so it can be cached aggressively; a
-          // pending one (no block yet) keeps the route's default no-store policy.
-          if (data.blockNumber !== null) Cache.setPolicy(c, Cache.policies.immutable)
+          // Mined chain data is immutable, while curated token fields can still
+          // change. Pending transactions keep the route's no-store policy.
+          if (data.blockNumber !== null)
+            Cache.setPolicy(
+              c,
+              query.include.some((resource) => resource.startsWith('feeToken.'))
+                ? Cache.policies.metadata
+                : Cache.policies.immutable,
+            )
 
           // The receipt is opt-in: fetching it is an extra RPC, so it only runs
           // when requested via `include=receipt` and the transaction is mined.
@@ -784,22 +782,24 @@ export function transactions() {
               const humanized = Receipts.humanizeReceipt(
                 Response.validated(Receipts.schema.Rpc.Receipt, receipt),
               )
-              data = { ...data, meta: { ...data.meta, receipt: humanized } }
+              const [receipt_enriched] = await enrichFeeTokens(c, {
+                chainId,
+                include: query.include,
+                rows: [humanized],
+              })
+              if (!receipt_enriched) throw new Error('Unable to enrich transaction receipt')
+              data = { ...data, meta: { ...data.meta, receipt: receipt_enriched } }
             }
           }
 
-          // Fee-token metadata is opt-in: resolving it is an extra RPC, so it
-          // only runs when requested via `include=feeToken` and the transaction
-          // declares a fee token (Tempo AA transactions).
-          const feeToken = data.feeToken
-          if (query.include.includes('feeToken') && feeToken !== undefined) {
-            const token = await Timing.time(c, 'fee_token', () =>
-              Tokens.resolveToken(c, { address: feeToken, chainId }).catch(() => undefined),
-            )
-            if (token) data = { ...data, meta: { ...data.meta, feeToken: token } }
-          }
+          const [data_enriched] = await enrichFeeTokens(c, {
+            chainId,
+            include: query.include,
+            rows: [data],
+          })
+          if (!data_enriched) throw new Error('Unable to enrich transaction')
 
-          return c.json(Response.validated(schema.getTransaction.Response, data), 200)
+          return c.json(Response.validated(schema.getTransaction.Response, data_enriched), 200)
         } catch (cause) {
           return Response.upstream(c, cause)
         }
@@ -808,10 +808,9 @@ export function transactions() {
 }
 
 /**
- * Lists humanized transactions and embeds opt-in `include` resources
- * (`feeToken`, `receipt`). A `status` filter routes the page through the
- * receipts list instead of the `txs` scan, since execution status lives on
- * receipts.
+ * Lists humanized transactions with required fee-token metadata and opt-in
+ * resources. Status filters page through receipts because execution status
+ * lives there.
  */
 export async function listTransactions(
   c: Context<App.Environment>,
@@ -858,6 +857,7 @@ export async function listTransactions(
   if (include.includes('receipt') && data.length > 0) {
     const receipts = await Receipts.embedReceipts(c, {
       chainId: rest.chainId,
+      include,
       receipts: receiptPage?.data,
       rows: data,
     })
@@ -866,13 +866,15 @@ export async function listTransactions(
       return receipt ? { ...row, meta: { ...row.meta, receipt } } : row
     })
   }
-  if (include.includes('feeToken')) data = await embedFeeTokens(c, data, rest.chainId)
-  return { ...page, data }
+  return {
+    ...page,
+    data: await enrichFeeTokens(c, { chainId: rest.chainId, include, rows: data }),
+  }
 }
 
 export declare namespace listTransactions {
   type Options = getTransactions.Options & {
-    /** Optional related resources to embed (e.g. `feeToken`, `receipt`). */
+    /** Optional receipt and curated token fields to embed. */
     include: readonly z.output<typeof schema.getTransaction.Include>[]
   }
 }
@@ -885,11 +887,8 @@ export declare namespace listTransactions {
  */
 async function transactionsForReceipts(
   c: Context<App.Environment>,
-  options: {
-    chainId: z.output<typeof Schema.ChainId>
-    receipts: readonly z.output<typeof Receipts.schema.Receipt>[]
-  },
-): Promise<z.output<typeof schema.Transaction>[]> {
+  options: transactionsForReceipts.Options,
+): Promise<humanizeTransaction.Output[]> {
   const { chainId, receipts } = options
   if (receipts.length === 0) return []
   const tidx = c.get('getTidx')(chainId)
@@ -907,7 +906,7 @@ async function transactionsForReceipts(
     }),
   )
 
-  const byHash = new Map<string, z.output<typeof schema.Transaction>>()
+  const byHash = new Map<string, humanizeTransaction.Output>()
   for (const row of result.rows) {
     const rpc = schema.Rpc.Transaction.safeParse(toRpcTransaction(row))
     if (rpc.success) byHash.set(rpc.data.hash.toLowerCase(), humanizeTransaction(rpc.data))
@@ -917,47 +916,110 @@ async function transactionsForReceipts(
     .filter((transaction) => transaction !== undefined)
 }
 
-/**
- * Resolves fee-token metadata for each row and embeds it under `meta.feeToken`,
- * sharing a single verified-token fetch. Best-effort: a row whose fee token
- * can't be resolved (or that has none) is returned unchanged. Shared by the
- * transaction and receipt list endpoints (and their address-scoped variants),
- * whose rows all carry an optional `feeToken` address and a `meta` object.
- */
-export async function embedFeeTokens<
-  row extends { feeToken?: Hex.Hex | undefined; meta: Record<string, unknown> },
->(c: Context<App.Environment>, rows: row[], chainId: z.output<typeof Schema.ChainId>) {
-  if (rows.length === 0) return rows
-  const uniqueTokens = Array.from(
-    new Set(
-      rows.map((row) => row.feeToken).filter((address): address is Hex.Hex => address != null),
+declare namespace transactionsForReceipts {
+  /** Inputs for matching receipt rows to transactions. */
+  type Options = {
+    /** Chain used to fetch matching transaction rows. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** Receipt positions and hashes in page order. */
+    receipts: readonly Receipt[]
+  }
+
+  /** Receipt fields needed for transaction hydration. */
+  type Receipt = {
+    /** Block containing the receipt. */
+    blockNumber: number
+    /** Hash of the transaction that produced the receipt. */
+    transactionHash: string
+  }
+}
+
+/** Resolves required fee-token metadata and optional curated fields without mutating input rows. */
+export async function enrichFeeTokens<const row extends object>(
+  c: Context<App.Environment>,
+  options: enrichFeeTokens.Options<row>,
+): Promise<enrichFeeTokens.Output<row>[]> {
+  const { chainId, include, rows } = options
+  const includeLogoUri = include.includes('feeToken.logoUri')
+  const includeVerified = include.includes('feeToken.verified')
+  const uniqueTokens = [
+    ...new Set(
+      rows
+        .map((row) => row.feeToken)
+        .filter((address): address is z.output<typeof Schema.Address> => address !== undefined)
+        .map((address) => address.toLowerCase())
+        .map((address) => Schema.Address.parse(address)),
     ),
-  )
-  if (uniqueTokens.length === 0) return rows
+  ]
+  if (uniqueTokens.length === 0)
+    return rows.map((row) => ({ ...row }) as enrichFeeTokens.Output<row>)
 
-  const snapshot = await VerifiedTokens.snapshot(c, chainId)
+  const snapshot =
+    includeLogoUri || includeVerified
+      ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+      : undefined
   const resolved = await Timing.time(c, 'tokens', () =>
     Promise.all(
-      uniqueTokens.map((token) =>
-        Tokens.resolveToken(c, {
-          address: token,
-          chainId,
-          snapshot,
-        })
-          .then((metadata) => [token, metadata] as const)
-          .catch(() => [token, undefined] as const),
-      ),
+      uniqueTokens.map(async (address) => {
+        const [logoUri, metadata] = await Promise.all([
+          includeLogoUri
+            ? Tokens.getTokenLogo(c, { address, chainId }).catch(() => undefined)
+            : Promise.resolve(undefined),
+          Tokens.getTokenMetadata(c, { address, chainId }),
+        ])
+        return [
+          address,
+          {
+            address,
+            currency: metadata.currency,
+            decimals: metadata.decimals,
+            ...(includeLogoUri
+              ? {
+                  logoUri: logoUri ?? snapshot?.byAddress.get(address)?.logoUri ?? metadata.logoUri,
+                }
+              : {}),
+            name: metadata.name,
+            symbol: metadata.symbol,
+            ...(includeVerified && snapshot ? { verified: snapshot.byAddress.has(address) } : {}),
+          },
+        ] as const
+      }),
     ),
   )
   const tokensByAddress = new Map(resolved)
   return rows.map((row) => {
-    const token = row.feeToken == null ? undefined : tokensByAddress.get(row.feeToken)
-    // The runtime shape stays `row`; the generic object spread just can't prove
-    // the override keeps it assignable to `row`.
-    return (token ? { ...row, meta: { ...row.meta, feeToken: token } } : row) as row
+    if (row.feeToken === undefined) return { ...row } as enrichFeeTokens.Output<row>
+    const address = Schema.Address.parse(row.feeToken.toLowerCase())
+    const feeToken = tokensByAddress.get(address)
+    if (!feeToken) throw new Error('Unable to resolve fee token metadata')
+    return { ...row, feeToken } as enrichFeeTokens.Output<row>
   })
 }
 
+export declare namespace enrichFeeTokens {
+  /** Fee-token enrichment inputs. */
+  type Options<row extends object> = {
+    /** Chain used for token metadata resolution. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** Requested optional token fields. */
+    include: readonly string[]
+    /** Rows carrying unresolved fee-token addresses. */
+    rows: readonly (row & Unresolved)[]
+  }
+
+  /** A copied row whose fee-token address has been replaced by metadata. */
+  type Output<row> = Omit<row, 'feeToken'> & {
+    /** Resolved fee-token metadata when the row declares a fee token. */
+    feeToken?: z.output<typeof Tokens.schema.TokenReference> | undefined
+  }
+
+  /** Row field before fee-token metadata resolution. */
+  type Unresolved = {
+    /** Fee-token address from indexed or RPC data. */
+    feeToken?: z.output<typeof Schema.Address> | undefined
+  }
+}
+
 export function getTransactions(c: Context<App.Environment>, options: getTransactions.Options) {
   const { chainId } = options
   const store = c.get('store')
@@ -1263,7 +1325,7 @@ export declare namespace scanTransactions {
     /** Keyset position of the row. */
     cursor: readonly [blockNumber: number, transactionIndex: number]
     /** The humanized transaction (same shape the read endpoint returns). */
-    data: z.output<typeof schema.Transaction>
+    data: humanizeTransaction.Output
   }
   /** A page of scanned transactions. */
   type Page = {
@@ -1334,7 +1396,7 @@ function humanizeCall(call: z.output<typeof schema.Call>): z.output<typeof schem
  */
 export function humanizeTransaction(
   rpc: z.output<typeof schema.Rpc.Transaction>,
-): z.output<typeof schema.Transaction> {
+): humanizeTransaction.Output {
   return {
     blockHash: rpc.blockHash,
     blockNumber: Value.hexToNumber(rpc.blockNumber) ?? null,
@@ -1361,3 +1423,11 @@ export function humanizeTransaction(
     value: Value.fromHex(rpc.value) ?? '0',
   }
 }
+
+export declare namespace humanizeTransaction {
+  /** Humanized fields before asynchronous fee-token metadata resolution. */
+  type Output = Omit<z.output<typeof schema.Transaction>, 'feeToken'> & {
+    /** Unresolved fee-token address from the RPC transaction. */
+    feeToken?: z.output<typeof Schema.Address> | undefined
+  }
+}