tapimo 0.5.2 → 0.6.0

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

@@ -17,12 +17,17 @@ import type * 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'
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
+import * as FxOracle from '../FxOracle.js'
 import * as Tokens from './tokens.js'
 import * as Transfers from './transfers.js'
+import * as Valuation from './valuation.js'
 
 /** Example transaction hash surfaced in OpenAPI docs. */
 const exampleHash = '0x4845ae2098724ab26a5d89370dce5124d044be6a5acc164afc348662de67d474'
 
+const tokenFields = ['token.logoUri', 'token.verified'] as const
+
 /** Zod schemas owned by the activity handlers. */
 export namespace schema {
   /** A signer: the literal `self`, or the access-key address that signed. */
@@ -32,20 +37,50 @@ export namespace schema {
       z.describe('Who signed the activity: `self`, or the access-key address used to sign it.'),
     )
 
-  /**
-   * A token and the amount that moved, in the same shape as the API's transfer
-   * resource (`Transfers.schema.SourceToken`): a contract `address` and a
-   * decimal-integer `amount`, plus best-effort `decimals`/`symbol` metadata when
-   * the token has been resolved.
-   */
-  export const Token = Transfers.schema.SourceToken
+  /** A token with required RPC metadata and optional curated fields. */
+  export const Token = Schema.describe(
+    Tokens.schema.TokenReference,
+    'A token referenced by an activity item.',
+  )
 
-  /**
-   * A token transfer as classified by the feed: the `/transfers` row shape
-   * plus the feed-only, subject-relative fields (`direction`, `signer`) that
-   * the unscoped resource cannot carry, with `memo`/`attribution` always
-   * resolved (the feed already decodes the underlying events).
-   */
+  /** A token amount carrying its nominal value in the requested denomination. */
+  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 ' +
+            'unverified, its display currency has no rate, or rates were unavailable.',
+        ),
+      ),
+  })
+
+  /** Self-contained amount for a destination token. */
+  const DestinationAmount = ValuedAmount.check(
+    z.describe('Amount associated with `destinationToken`.'),
+  )
+
+  /** Self-contained amount for a refunded token. */
+  const RefundAmount = ValuedAmount.check(z.describe('Amount associated with `refund`.'))
+
+  /** Self-contained amount for a source token. */
+  const SourceAmount = ValuedAmount.check(z.describe('Amount associated with `sourceToken`.'))
+
+  /** Page-level resources: valuation rate provenance. */
+  export const Meta = z
+    .object({
+      pricing: 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.',
+          ),
+        ),
+    })
+    .check(z.describe('Page-level resources attached to this response.'))
+
+  /** A token transfer with subject-relative direction and signer fields. */
   export const Transfer = z
     .object({
       attribution: z
@@ -64,11 +99,18 @@ export namespace schema {
           z.describe('Block number where this transfer was included.'),
           z.meta({ examples: [12345678] }),
         ),
+      destinationAmount: z
+        .optional(DestinationAmount)
+        .check(
+          z.describe(
+            'Amount delivered to the recipient for a cross-token transfer. Omitted with `destinationToken` for a same-token transfer.',
+          ),
+        ),
       destinationToken: z
         .optional(Token)
         .check(
           z.describe(
-            'Token and amount delivered to the recipient when it differs from the source token — a cross-token transfer routed through the DEX. Omitted for a same-token transfer.',
+            'Token delivered to the recipient when it differs from the source token. Omitted for a same-token transfer.',
           ),
         ),
       direction: z
@@ -90,7 +132,8 @@ export namespace schema {
             'For outbound transfers, who signed it: `self` or the access-key address. Omitted for inbound transfers.',
           ),
         ),
-      sourceToken: Token.check(z.describe('Token and amount that moved in the transfer.')),
+      sourceAmount: SourceAmount,
+      sourceToken: Token.check(z.describe('Token that moved in the transfer.')),
       timestamp: z
         .iso.datetime()
         .check(z.describe('Block timestamp for the transfer.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })), // prettier-ignore
@@ -98,7 +141,16 @@ export namespace schema {
         z.describe('Transaction hash that contains this transfer.'),
       ),
     })
-    .check(z.describe('One token transfer involving the requested address.'))
+    .check(
+      z.refine(
+        (data) => (data.destinationToken === undefined) === (data.destinationAmount === undefined),
+        {
+          error: '`destinationAmount` and `destinationToken` must be returned together.',
+          path: ['destinationAmount'],
+        },
+      ),
+      z.describe('One token transfer involving the requested address.'),
+    )
 
   /**
    * One transaction log, decoded into a known Tempo event when possible. The
@@ -193,9 +245,7 @@ export namespace schema {
       .object({
         ...base,
         data: Transfer.check(
-          z.describe(
-            'Transfer details, using the `/transfers` shape plus feed-only fields such as direction and signer.',
-          ),
+          z.describe('Transfer details with feed-relative direction and signer fields.'),
         ),
         type: z
           .literal('transfer')
@@ -208,7 +258,8 @@ export namespace schema {
         data: z
           .object({
             recipient: Schema.Address.check(z.describe('Address that received the transfer.')),
-            sourceToken: Token.check(z.describe('Token and amount that were minted.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token that was minted.')),
           })
           .check(z.describe('A token mint activity.')),
         type: z
@@ -223,7 +274,8 @@ export namespace schema {
           .object({
             sender: Schema.Address.check(z.describe('Address whose token balance was burned.')),
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount that were burned.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token that was burned.')),
           })
           .check(z.describe('A token burn activity.')),
         type: z
@@ -236,8 +288,10 @@ export namespace schema {
         ...base,
         data: z
           .object({
+            destinationAmount: DestinationAmount,
             destinationToken: Token.check(z.describe('Token the address received in the swap.')),
             signer: Signer,
+            sourceAmount: SourceAmount,
             sourceToken: Token.check(z.describe('Token the address sent into the swap.')),
           })
           .check(
@@ -256,9 +310,8 @@ export namespace schema {
         data: z
           .object({
             signer: Signer,
-            sourceToken: Token.check(
-              z.describe('Token and allowance amount approved for spending.'),
-            ),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token approved for spending.')),
             spender: Schema.Address.check(
               z.describe('Address allowed to spend the approved amount.'),
             ),
@@ -277,9 +330,18 @@ export namespace schema {
             refund: z
               .optional(Token)
               .check(z.describe('Token refunded to the address when the session closed, if any.')),
+            refundAmount: z
+              .optional(RefundAmount)
+              .check(z.describe('Amount refunded to the address when the session closed, if any.')),
             signer: Signer,
           })
-          .check(z.describe('A payment-channel session close activity.')),
+          .check(
+            z.refine((data) => (data.refund === undefined) === (data.refundAmount === undefined), {
+              error: '`refundAmount` and `refund` must be returned together.',
+              path: ['refundAmount'],
+            }),
+            z.describe('A payment-channel session close activity.'),
+          ),
         type: z
           .literal('session-closed')
           .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
@@ -354,7 +416,8 @@ export namespace schema {
               z.describe('Address whose blocked balance was burned by policy.'),
             ),
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount that were burned.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token that was burned.')),
           })
           .check(
             z.describe(
@@ -377,9 +440,8 @@ export namespace schema {
             ),
             payer: Schema.Address.check(z.describe('Address that funds the channel.')),
             signer: Signer,
-            sourceToken: Token.check(
-              z.describe('Token and deposit amount locked into the channel.'),
-            ),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token locked into the channel.')),
           })
           .check(z.describe('A payment channel was opened and funded.')),
         type: z
@@ -394,7 +456,8 @@ export namespace schema {
           .object({
             channelId: Schema.Hex.check(z.describe('Identifier of the payment channel.')),
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount added to the channel deposit.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token added to the channel deposit.')),
           })
           .check(z.describe('A payment channel deposit was topped up.')),
         type: z
@@ -411,7 +474,8 @@ export namespace schema {
             payee: Schema.Address.check(z.describe('Address that received the settled payment.')),
             payer: Schema.Address.check(z.describe('Address that funded the channel.')),
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount paid out in this settlement.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token paid out in this settlement.')),
           })
           .check(z.describe('An incremental payment-channel settlement to the payee.')),
         type: z
@@ -431,13 +495,30 @@ export namespace schema {
             payer: Schema.Address.check(z.describe('Address that funded the channel.')),
             refund: z
               .optional(Token)
-              .check(z.describe('Token and amount refunded to the payer on close, if any.')),
+              .check(z.describe('Token refunded to the payer on close, if any.')),
+            refundAmount: z
+              .optional(RefundAmount)
+              .check(z.describe('Amount refunded to the payer on close, if any.')),
             signer: Signer,
+            sourceAmount: z
+              .optional(SourceAmount)
+              .check(z.describe('Final amount paid to the payee on close, if any.')),
             sourceToken: z
               .optional(Token)
-              .check(z.describe('Token and final amount paid out to the payee on close, if any.')),
+              .check(z.describe('Token paid out to the payee on close, if any.')),
           })
           .check(
+            z.refine((data) => (data.refund === undefined) === (data.refundAmount === undefined), {
+              error: '`refundAmount` and `refund` must be returned together.',
+              path: ['refundAmount'],
+            }),
+            z.refine(
+              (data) => (data.sourceToken === undefined) === (data.sourceAmount === undefined),
+              {
+                error: '`sourceAmount` and `sourceToken` must be returned together.',
+                path: ['sourceAmount'],
+              },
+            ),
             z.describe(
               'A payment channel was closed, paying out the payee and refunding the payer.',
             ),
@@ -475,7 +556,8 @@ export namespace schema {
               .enum(['bid', 'ask'])
               .check(z.describe('Order side: `bid` buys the base token, `ask` sells it.'), z.meta({ examples: ['bid'] })), // prettier-ignore
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount escrowed for the order.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token escrowed for the order.')),
             tick: z
               .number()
               .check(
@@ -512,7 +594,8 @@ export namespace schema {
         data: z
           .object({
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount of fees distributed.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token used for the distributed fees.')),
             validator: Schema.Address.check(
               z.describe('Validator that received the distributed fees.'),
             ),
@@ -528,11 +611,11 @@ export namespace schema {
         ...base,
         data: z
           .object({
-            destinationToken: Token.check(
-              z.describe('Token and amount received from the fee AMM.'),
-            ),
+            destinationAmount: DestinationAmount,
+            destinationToken: Token.check(z.describe('Token received from the fee AMM.')),
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount sent into the fee AMM.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token sent into the fee AMM.')),
             swapper: Schema.Address.check(z.describe('Address that performed the rebalance swap.')),
           })
           .check(z.describe('A fee-AMM rebalance swap between a validator and user token.')),
@@ -548,7 +631,8 @@ export namespace schema {
           .object({
             funder: Schema.Address.check(z.describe('Address that funded the reward pool.')),
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount added to the reward pool.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token added to the reward pool.')),
           })
           .check(z.describe('A token reward pool was funded.')),
         type: z
@@ -583,9 +667,8 @@ export namespace schema {
               z.describe('Public key of the access key whose limit changed.'),
             ),
             signer: Signer,
-            sourceToken: Token.check(
-              z.describe('Token and new spending limit set for the access key.'),
-            ),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token whose spending limit was updated.')),
           })
           .check(z.describe('An access key’s per-token spending limit was updated.')),
         type: z
@@ -636,7 +719,8 @@ export namespace schema {
               .enum(['bid', 'ask'])
               .check(z.describe('Side of the flipped order: `bid` buys the base token, `ask` sells it.'), z.meta({ examples: ['bid'] })), // prettier-ignore
             signer: Signer,
-            sourceToken: Token.check(z.describe('Token and amount the flipped order rests with.')),
+            sourceAmount: SourceAmount,
+            sourceToken: Token.check(z.describe('Token the flipped order rests with.')),
             tick: z
               .number()
               .check(
@@ -1292,6 +1376,17 @@ export namespace schema {
     .union([...items, Group])
     .check(z.describe('Either one activity item, or a grouped set of access-key activity items.'))
 
+  /** Optional token fields that require sources beyond RPC metadata. */
+  export const Include = z
+    .enum(tokenFields)
+    .check(z.describe('Additional token fields to include in activity responses.'))
+
+  /** Parses comma-separated optional token fields. */
+  export const includeQuery = Schema.includeQuery(
+    Include,
+    'Comma-separated token fields to include, such as `token.logoUri,token.verified`.',
+  )
+
   /** Schemas for the getAddressActivities operation. */
   export namespace getAddressActivities {
     /** Path parameters for address activity requests. */
@@ -1308,6 +1403,7 @@ export namespace 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)
@@ -1317,6 +1413,7 @@ export namespace schema {
             ),
             z.meta({ examples: [true] }),
           ),
+        include: includeQuery,
         limit: Schema.Limit,
         // Raw-log capture is opt-in: it can add a large `events` array to every
         // item, so the default feed stays lean.
@@ -1344,6 +1441,9 @@ export namespace schema {
     export const Response = z
       .object({
         data: z.array(Entry).check(z.describe('Activity feed entries for the address.')),
+        meta: z
+          .optional(schema.Meta)
+          .check(z.describe('Page-level resources, such as valuation rate provenance.')),
         nextCursor: Schema.NextCursor,
       })
       .check(z.describe('A page of human-readable activity for the address.'))
@@ -1366,6 +1466,8 @@ export namespace schema {
     export const Query = z
       .strictObject({
         chainId: Schema.ChainIdQuery,
+        denomination: Schema.Denomination,
+        include: 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
@@ -1388,12 +1490,15 @@ export namespace schema {
     export const Response = z
       .object({
         data: z.array(Item).check(z.describe('Activity items classified from the transaction.')),
+        meta: z
+          .optional(schema.Meta)
+          .check(z.describe('Page-level resources, such as valuation rate provenance.')),
       })
       .check(z.describe('The human-readable activity that happened on a transaction.'))
   }
 }
 
-/** A token and amount in the public resource shape (derived from {@link schema.Token}). */
+/** A token in the public resource shape (derived from {@link schema.Token}). */
 export type Token = z.output<typeof schema.Token>
 
 /** A single classified activity item (derived from {@link schema.Item}). */
@@ -1402,14 +1507,36 @@ export type Item = z.output<typeof schema.Item>
 /** A single activity item, or a folded access-key group (derived from {@link schema.Entry}). */
 export type Entry = z.output<typeof schema.Entry>
 
+type AmountKey = 'destinationAmount' | 'refundAmount' | 'sourceAmount'
+type TokenKey = 'destinationToken' | 'refund' | 'sourceToken'
+
+/** Token fields available before RPC metadata resolution. */
+type UnenrichedToken = {
+  address: Token['address']
+  amount: z.output<typeof Schema.DecimalString>
+}
+
+type UnenrichedData<data> = {
+  [key in keyof data as key extends AmountKey ? never : key]: key extends TokenKey
+    ? UnenrichedToken | Extract<data[key], undefined>
+    : data[key]
+}
+
+/** A classified item whose token stubs have not been enriched with structured amounts. */
+type UnenrichedItem = {
+  [type in Item['type']]: Omit<Extract<Item, { type: type }>, 'data'> & {
+    data: UnenrichedData<Extract<Item, { type: type }>['data']>
+  }
+}[Item['type']]
+
 /**
  * A classified item before {@link list} stamps its display {@link Item.title}.
  * Internal classifiers build these; `list` derives `title` from `type` via
  * {@link titleByType}, so each branch never repeats the human label.
  */
 type RawItem = {
-  [type in Item['type']]: Omit<Extract<Item, { type: type }>, 'title'>
-}[Item['type']]
+  [type in UnenrichedItem['type']]: Omit<Extract<UnenrichedItem, { type: type }>, 'title'>
+}[UnenrichedItem['type']]
 
 /**
  * Human-readable label for each activity {@link Item.type}, mirroring the per-variant
@@ -1572,6 +1699,12 @@ const maxGroupSize = 50
 /** Token-bearing keys on an item's `data` payload, walked for enrichment. */
 const tokenKeys = ['destinationToken', 'refund', 'sourceToken'] as const
 
+const amountKeyByTokenKey = {
+  destinationToken: 'destinationAmount',
+  refund: 'refundAmount',
+  sourceToken: 'sourceAmount',
+} as const
+
 /** The base fields ({@link schema.base}) every activity item carries. */
 type Base = {
   id: string
@@ -1665,7 +1798,8 @@ type TxGroup = {
  * consecutive access-key-signed items into `group` entries. Pagination uses the
  * same `(block_num, tx_idx)` keyset cursor the pipeline emits.
  */
-export function addresses() {
+export function addresses(options: addresses.Options = {}) {
+  const oracle = options.fx?.oracle ?? FxOracle.ecb()
   return new Hono<App.Environment>().get(
     '/v1/addresses/:address/activities',
     Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -1682,7 +1816,7 @@ export function addresses() {
         'Get a human-readable feed of what an address has been doing onchain, including payments sent and received, swaps, approvals, and more.',
       operationId: 'getAddressActivities',
       responses: OpenApi.responses({
-        errors: { 502: 'Tempo could not read activity data from the upstream indexer.' },
+        errors: { 502: 'Tempo could not read activity or token data from an upstream service.' },
         success: {
           description: 'A page of address activity entries.',
           schema: schema.getAddressActivities.Response,
@@ -1712,38 +1846,42 @@ export function addresses() {
       const { 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 route's short `feed`
-      // default.
-      if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+      // Cursor pages carry current valuations and curated verification data.
+      if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.metadata)
 
       try {
         const chainId = query.chainId ?? c.get('chainId')
         const provider = tidx({ chainId, tidx: c.get('getTidx')(chainId) })
-        const { items, nextCursor } = await Timing.time(c, 'address_activities', () =>
-          Store.memoize(
-            () =>
-              list(provider, {
-                address: address as Hex.Hex,
-                cursor: query.cursor,
-                group: query.group,
-                limit: query.limit,
-                logs: query.logs,
+        const { items: unenrichedItems, nextCursor } = await Timing.time(
+          c,
+          'address_activities',
+          () =>
+            Store.memoize(
+              () =>
+                list(provider, {
+                  address: address as Hex.Hex,
+                  cursor: query.cursor,
+                  group: query.group,
+                  limit: query.limit,
+                  logs: query.logs,
+                  store: c.get('store'),
+                }),
+              {
+                key: `activities:v1:${chainId}:${address.toLowerCase()}:${query.group ?? false}:${query.logs ?? false}:${query.cursor ?? 'head'}:${query.limit}`,
                 store: c.get('store'),
-              }),
-            {
-              key: `activities:v1:${chainId}:${address.toLowerCase()}:${query.group ?? false}:${query.logs ?? false}:${query.cursor ?? 'head'}:${query.limit}`,
-              store: c.get('store'),
-              ttl: Ttl.seconds(15),
-            },
-          ),
+                ttl: Ttl.seconds(15),
+              },
+            ),
         )
 
-        // Resolve token metadata for every token referenced across the page and
-        // spread it into each item's stub tokens. Goes through the shared
-        // `Tokens.getTokenMetadata` path so it reuses the `token:v1:…` cache with
-        // `/tokens` and `/transfers` instead of a parallel metadata fetch.
-        await enrichTokens(c, { chainId, items })
+        // Build immutable token and structured amount copies from RPC metadata.
+        const { items, rates } = await enrichTokens(c, {
+          chainId,
+          denomination: query.denomination ?? 'USD',
+          include: query.include,
+          items: unenrichedItems,
+          oracle,
+        })
 
         // Fold consecutive access-key-signed items into `group` entries only
         // when requested; otherwise every item is returned at the root.
@@ -1752,17 +1890,28 @@ export function addresses() {
         return c.json(
           Response.validated(schema.getAddressActivities.Response, {
             data,
+            ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
             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)
       }
     },
   )
 }
 
+export declare namespace addresses {
+  /** Options for the address-scoped activity handlers. */
+  type Options = {
+    /** FX configuration backing amount valuation. */
+    fx?: Valuation.addresses.Fx | undefined
+  }
+}
+
 /**
  * Creates transaction-scoped activity handlers, mounted under the
  * `/transactions` composer. Exposes `GET /:transactionHash/activities`.
@@ -1773,7 +1922,8 @@ export function addresses() {
  * classified item(s) — usually one headline activity — with the full per-tx
  * event set available via `logs=true`.
  */
-export function transactions() {
+export function transactions(options: transactions.Options = {}) {
+  const oracle = options.fx?.oracle ?? FxOracle.ecb()
   return new Hono<App.Environment>().get(
     '/v1/transactions/:transactionHash/activities',
     Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -1795,7 +1945,7 @@ export function transactions() {
             description: 'No mined transaction was found for that hash.',
             codes: ['transaction_not_found'],
           },
-          502: 'Tempo could not read activity data from the upstream indexer.',
+          502: 'Tempo could not read activity or token data from an upstream service.',
         },
         success: {
           description: 'The classified activity for the transaction.',
@@ -1806,10 +1956,8 @@ export function transactions() {
       tags: ['Activities'],
     }),
     Cache.response<App.Environment>({
-      // Activity exists only once the transaction is mined; once mined it is
-      // immutable. Default to no-store so a 404 (unknown / not-yet-mined hash)
-      // is not cached with a long header that would mask the eventual result;
-      // the handler upgrades the 200 to `immutable` below.
+      // Default to no-store so a 404 does not mask the eventual mined result.
+      // Successful responses use the metadata policy for current valuations.
       cacheControl: Cache.policies.noStore,
       name: 'tempo-api:transactions:v1',
       key: (c) => Cache.urlKey(c, schema.getTransactionActivities.Query),
@@ -1832,7 +1980,7 @@ export function transactions() {
       const chainId = query.chainId ?? c.get('chainId')
 
       try {
-        const items = await Timing.time(c, 'transaction_activities', () =>
+        const unenrichedItems = await Timing.time(c, 'transaction_activities', () =>
           Store.memoize(
             () =>
               getTransactionActivities({
@@ -1850,31 +1998,49 @@ export function transactions() {
           ),
         )
 
-        if (items === null)
+        if (unenrichedItems === null)
           return Response.error(c, {
             code: 'transaction_not_found',
             message: 'Transaction not found',
             status: 404,
           })
 
-        // A mined transaction's activity is final, so cache it aggressively.
-        Cache.setPolicy(c, Cache.policies.immutable)
+        // Mined activity still carries current valuations and verification data.
+        Cache.setPolicy(c, Cache.policies.metadata)
 
-        // Resolve token metadata for every token referenced and spread it into
-        // each item's stub tokens (shared `token:v1:…` cache path).
-        await enrichTokens(c, { chainId, items })
+        // Build immutable token and structured amount copies from RPC metadata.
+        const { items, rates } = await enrichTokens(c, {
+          chainId,
+          denomination: query.denomination ?? 'USD',
+          include: query.include,
+          items: unenrichedItems,
+          oracle,
+        })
 
         return c.json(
-          Response.validated(schema.getTransactionActivities.Response, { data: items }),
+          Response.validated(schema.getTransactionActivities.Response, {
+            data: items,
+            ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+          }),
           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 transactions {
+  /** Options for the transaction-scoped activity handlers. */
+  type Options = {
+    /** FX configuration backing amount valuation. */
+    fx?: Valuation.addresses.Fx | undefined
+  }
+}
+
 /**
  * Classifies the activity for a single transaction. Fetches the transaction's
  * receipt (for its block position, sender, and fee payer) and its logs, then
@@ -1887,7 +2053,7 @@ export function transactions() {
  */
 export async function getTransactionActivities(
   options: getTransactionActivities.Options,
-): Promise<Item[] | null> {
+): Promise<UnenrichedItem[] | null> {
   const { chainId, logs = false, tidx: tidxClient } = options
   const hash = options.transactionHash.toLowerCase()
 
@@ -1979,7 +2145,7 @@ export async function list(provider: Provider, options: list.Options): Promise<l
   const fingerprintMap = await Mpp.fingerprintMap({ store: options.store }).catch(() => ({}))
 
   let currentCursor: string | undefined = cursor
-  const allItems: Item[] = []
+  const allItems: UnenrichedItem[] = []
   let hasMore = false
   let lastGroup: TxGroup | undefined
 
@@ -2005,7 +2171,7 @@ export async function list(provider: Provider, options: list.Options): Promise<l
     lastGroup = page[page.length - 1]
 
     const enough = group
-      ? groupByAccessKey(allItems).length >= minGroupEntries
+      ? groupByAccessKeyItems(allItems).length >= minGroupEntries
       : allItems.length >= limit
     if (enough || !hasMore) break
 
@@ -2015,8 +2181,8 @@ export async function list(provider: Provider, options: list.Options): Promise<l
   let nextCursor: string | null = null
   if (hasMore && lastGroup) nextCursor = provider.cursorForGroup(lastGroup)
 
-  // Items carry stub tokens (`address`/`amount`); the caller enriches them with
-  // metadata via {@link enrichTokens}.
+  // Items carry private `address`/`amount` stubs; the caller splits them into
+  // public token references and structured amounts via {@link enrichTokens}.
   return { items: allItems, nextCursor }
 }
 
@@ -2038,7 +2204,7 @@ export declare namespace list {
   }
   /** Result of {@link list}. */
   type ReturnType = {
-    items: Item[]
+    items: UnenrichedItem[]
     nextCursor: string | null
   }
 }
@@ -3661,13 +3827,13 @@ function transfer(
   blockNumber: number,
   data: {
     attribution?: string | undefined
-    destinationToken?: Token | undefined
+    destinationToken?: UnenrichedToken | undefined
     direction: 'in' | 'out'
     memo?: string | undefined
     recipient: Address.Address
     sender: Address.Address
     signer?: 'self' | Address.Address | undefined
-    sourceToken: Token
+    sourceToken: UnenrichedToken
   },
 ): Extract<RawItem, { type: 'transfer' }> {
   return {
@@ -3792,75 +3958,154 @@ function lowerOrNull(value: unknown): Address.Address | null {
   return text ? (text.toLowerCase() as Address.Address) : null
 }
 
-/** Builds a stub token; `decimals`/`symbol` are filled by {@link enrichItem}. */
-function token(amount: bigint | undefined, address: Address.Address): Token {
+/** Builds a token stub whose metadata is filled by {@link enrichItem}. */
+function token(amount: bigint | undefined, address: Address.Address): UnenrichedToken {
   return { address: address.toLowerCase() as Address.Address, amount: (amount ?? 0n).toString() }
 }
 
 /** Collects every token address referenced by an item's `data`. */
-function collectTokens(item: Item, set: Set<Address.Address>) {
-  const data = item.data as Partial<Record<(typeof tokenKeys)[number], Token>>
+function collectTokens(item: UnenrichedItem, set: Set<Address.Address>) {
+  const data = item.data as Partial<Record<(typeof tokenKeys)[number], UnenrichedToken>>
   for (const key of tokenKeys) {
     const t = data[key]
     if (t) set.add(t.address.toLowerCase() as Address.Address)
   }
 }
 
-/** Resolved token metadata keyed by lowercased address. */
-type ResolvedToken = Awaited<ReturnType<typeof Tokens.getTokenMetadata>>
+/** Resolved token fields keyed by lowercased address. */
+type ResolvedToken = {
+  currency: string
+  decimals: number
+  logoUri?: string | undefined
+  name: string
+  symbol: string
+  verified?: boolean | undefined
+}
 
-/**
- * Resolves metadata for every token referenced across a page of items and
- * spreads it into each item's stub tokens, in place. Routes through the shared
- * {@link Tokens.getTokenMetadata} (one `token.getMetadata` RPC per token,
- * memoized under the `token:v1:…` key shared with `/tokens` and `/transfers`)
- * instead of a parallel metadata fetch. Resolution is best-effort: a token
- * whose metadata is unavailable keeps just `address`/`amount`.
- */
-async function enrichTokens(c: Context<App.Environment>, options: enrichTokens.Options) {
-  const { chainId, items } = options
+/** Resolves core metadata into immutable items. Optional logo and verification sources are best-effort. */
+async function enrichTokens(
+  c: Context<App.Environment>,
+  options: enrichTokens.Options,
+): Promise<{ items: Item[]; rates: FxOracle.RateSet | undefined }> {
+  const { chainId, denomination, include, items, oracle } = options
   const addresses = new Set<Address.Address>()
   for (const item of items) collectTokens(item, addresses)
-  if (addresses.size === 0) return
+  // Valuation keys off the curated snapshot; a snapshot failure degrades the
+  // values to `null` rather than failing the feed.
+  const snapshot =
+    addresses.size > 0
+      ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+      : undefined
+  const rates = await Valuation.ratesFor(c, {
+    currencies: snapshot
+      ? [...addresses].flatMap((address) => {
+          const held = snapshot.byAddress.get(address)?.currency
+          return held === undefined ? [] : [held]
+        })
+      : [],
+    denomination,
+    oracle,
+  })
+  if (addresses.size === 0) return { items: items as Item[], rates }
+
+  const includeLogoUri = include.includes('token.logoUri')
+  const includeVerified = include.includes('token.verified')
 
   const resolved = await Timing.time(c, 'tokens', () =>
     Promise.all(
-      [...addresses].map((address) =>
-        Tokens.getTokenMetadata(c, { address, chainId })
-          .then((metadata) => [address.toLowerCase(), metadata] as const)
-          .catch(() => [address.toLowerCase(), undefined] as const),
-      ),
+      [...addresses].map(async (address) => {
+        const [logoUri, metadata] = await Promise.all([
+          includeLogoUri
+            ? Tokens.getTokenLogo(c, { address, chainId }).catch(() => undefined)
+            : undefined,
+          Tokens.getTokenMetadata(c, { address, chainId }),
+        ])
+        return [
+          address.toLowerCase(),
+          {
+            currency: metadata.currency,
+            decimals: metadata.decimals,
+            logoUri: includeLogoUri
+              ? (logoUri ?? snapshot?.byAddress.get(address)?.logoUri ?? metadata.logoUri)
+              : undefined,
+            name: metadata.name,
+            symbol: metadata.symbol,
+            verified: includeVerified && snapshot ? snapshot.byAddress.has(address) : undefined,
+          },
+        ] as const
+      }),
     ),
   )
   const byAddress = new Map(resolved)
-  for (const item of items) enrichItem(item, byAddress)
+  return {
+    items: items.map((item) => enrichItem(item, byAddress, { denomination, rates, snapshot })),
+    rates,
+  }
 }
 
 declare namespace enrichTokens {
   type Options = {
     chainId: z.output<typeof Schema.ChainId>
-    items: readonly Item[]
+    /** Currency the amount valuations are denominated in (uppercase). */
+    denomination: string
+    include: readonly z.output<typeof schema.Include>[]
+    items: readonly UnenrichedItem[]
+    /** FX rate oracle backing amount valuation. */
+    oracle: FxOracle.Oracle
   }
 }
 
-/** Spreads resolved token metadata into an item's stub tokens, in place. */
-function enrichItem(item: Item, byAddress: Map<string, ResolvedToken | undefined>) {
-  const data = item.data as Partial<Record<(typeof tokenKeys)[number], Token>>
+/** Returns an enriched copy of an item without mutating its cached token stubs. */
+function enrichItem(
+  item: UnenrichedItem,
+  byAddress: Map<string, ResolvedToken>,
+  valuation: enrichItem.Valuation,
+): Item {
+  const source = item.data as Partial<Record<(typeof tokenKeys)[number], UnenrichedToken>>
+  const data: Record<string, unknown> = { ...item.data }
   for (const key of tokenKeys) {
-    const t = data[key]
+    const t = source[key]
     if (!t) continue
     const meta = byAddress.get(t.address.toLowerCase())
-    if (!meta) continue
-    // Carry only the per-row token fields the `Token` (SourceToken) shape
-    // declares; `address`/`amount` come from the stub.
+    if (!meta) throw new Error(`Token metadata unavailable for ${t.address}`)
+
+    data[amountKeyByTokenKey[key]] = {
+      ...Value.tokenAmount({
+        baseUnits: t.amount,
+        currency: meta.currency,
+        decimals: meta.decimals,
+      }),
+      // Valued via the curated display currency, never the on-chain metadata.
+      valuation: Valuation.valuationFor({
+        amount: BigInt(t.amount),
+        denomination: valuation.denomination,
+        rates: valuation.rates,
+        token: valuation.snapshot?.byAddress.get(t.address.toLowerCase()),
+      }),
+    }
     data[key] = {
-      ...t,
+      address: t.address,
       currency: meta.currency,
       decimals: meta.decimals,
+      ...(meta.logoUri !== undefined ? { logoUri: meta.logoUri } : {}),
       name: meta.name,
       symbol: meta.symbol,
+      ...(meta.verified !== undefined ? { verified: meta.verified } : {}),
     }
   }
+  return { ...item, data } as Item
+}
+
+declare namespace enrichItem {
+  /** Valuation inputs threaded from {@link enrichTokens}. */
+  type Valuation = {
+    /** Currency the amount valuations are denominated in (uppercase). */
+    denomination: string
+    /** Oracle rate set, when loaded. */
+    rates: FxOracle.RateSet | undefined
+    /** Compiled verified-token snapshot, when available. */
+    snapshot: VerifiedTokens.Snapshot | undefined
+  }
 }
 
 /**
@@ -3869,8 +4114,31 @@ function enrichItem(item: Item, byAddress: Map<string, ResolvedToken | undefined
  * Must be called once over the full, timestamp-sorted item list.
  */
 export function groupByAccessKey(items: Item[]): Entry[] {
-  const entries: Entry[] = []
-  let currentGroup: { items: Item[]; signer: Address.Address } | null = null
+  return groupByAccessKeyItems(items)
+}
+
+type GroupableItem = {
+  data: object
+  id: string
+  perspective: 'incoming' | 'outgoing'
+  timestamp: string
+}
+
+type GroupedItem<item extends GroupableItem> =
+  | item
+  | {
+      data: { items: item[]; signer: Address.Address }
+      id: string
+      perspective: 'incoming' | 'outgoing'
+      timestamp: string
+      title: 'Group'
+      type: 'group'
+    }
+
+/** Groups items while preserving whether their token data has been enriched. */
+function groupByAccessKeyItems<item extends GroupableItem>(items: item[]): GroupedItem<item>[] {
+  const entries: GroupedItem<item>[] = []
+  let currentGroup: { items: item[]; signer: Address.Address } | null = null
 
   for (const item of items) {
     const itemSigner = signerOf(item)
@@ -3903,12 +4171,15 @@ export function groupByAccessKey(items: Item[]): Entry[] {
 }
 
 /** The access-key signer of an item, or `self` when it has no access-key signer. */
-function signerOf(item: Item): 'self' | Address.Address {
+function signerOf(item: GroupableItem): 'self' | Address.Address {
   return (item.data as { signer?: 'self' | Address.Address }).signer ?? 'self'
 }
 
 /** Unwraps single-item groups; otherwise wraps the items in a `group` entry. */
-function flushGroup(group: { items: Item[]; signer: Address.Address }): Entry {
+function flushGroup<item extends GroupableItem>(group: {
+  items: item[]
+  signer: Address.Address
+}): GroupedItem<item> {
   if (group.items.length === 1) return group.items[0]!
   const firstItem = group.items[0]!
   const lastItem = group.items[group.items.length - 1]!