tapimo 0.5.3 → 0.7.0

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

@@ -1,6 +1,7 @@
 import { Hono } from 'hono';
 import { Address, Hex } from 'ox';
 import { parseEventLogs, zeroAddress } from 'viem';
+import { token as viem_Token } from 'viem/actions';
 import { Abis, Addresses } from 'viem/tempo';
 import * as z from 'zod/mini';
 import * as Auth from '../../../internal/Auth.js';
@@ -14,10 +15,17 @@ 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 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'];
+// TIP-20 tokens live at deterministic `0x20c0…` addresses. Other contracts
+// can emit the same `Transfer` signature but do not expose TIP-20 metadata.
+const tip20AddressPrefix = '0x20c0';
 /** Zod schemas owned by the activity handlers. */
 export var schema;
 (function (schema) {
@@ -25,19 +33,31 @@ export var schema;
     const Signer = z
         .union([z.literal('self'), Schema.Address])
         .check(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.
-     */
-    schema.Token = Transfers.schema.SourceToken;
-    /**
-     * 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 with required RPC metadata and optional curated fields. */
+    schema.Token = Schema.describe(Tokens.schema.TokenReference, 'A token referenced by an activity item.');
+    /** 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. */
+    schema.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. */
     schema.Transfer = z
         .object({
         attribution: z
@@ -46,9 +66,12 @@ export var schema;
         blockNumber: z
             .number()
             .check(z.int(), z.nonnegative(), 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(schema.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.')),
+            .check(z.describe('Token delivered to the recipient when it differs from the source token. Omitted for a same-token transfer.')),
         direction: z
             .enum(['in', 'out'])
             .check(z.describe('The address’s side of the transfer: `in` means received, and `out` means sent.')),
@@ -60,13 +83,17 @@ export var schema;
         signer: z
             .optional(Signer)
             .check(z.describe('For outbound transfers, who signed it: `self` or the access-key address. Omitted for inbound transfers.')),
-        sourceToken: schema.Token.check(z.describe('Token and amount that moved in the transfer.')),
+        sourceAmount: SourceAmount,
+        sourceToken: schema.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
         transactionHash: Schema.Hash.check(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
      * raw fields (`address`/`data`/`logIndex`/`topics`) are always present so no
@@ -126,7 +153,7 @@ export var schema;
         z
             .object({
             ...base,
-            data: schema.Transfer.check(z.describe('Transfer details, using the `/transfers` shape plus feed-only fields such as direction and signer.')),
+            data: schema.Transfer.check(z.describe('Transfer details with feed-relative direction and signer fields.')),
             type: z
                 .literal('transfer')
                 .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
@@ -138,7 +165,8 @@ export var schema;
             data: z
                 .object({
                 recipient: Schema.Address.check(z.describe('Address that received the transfer.')),
-                sourceToken: schema.Token.check(z.describe('Token and amount that were minted.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token that was minted.')),
             })
                 .check(z.describe('A token mint activity.')),
             type: z
@@ -153,7 +181,8 @@ export var schema;
                 .object({
                 sender: Schema.Address.check(z.describe('Address whose token balance was burned.')),
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and amount that were burned.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token that was burned.')),
             })
                 .check(z.describe('A token burn activity.')),
             type: z
@@ -166,8 +195,10 @@ export var schema;
             ...base,
             data: z
                 .object({
+                destinationAmount: DestinationAmount,
                 destinationToken: schema.Token.check(z.describe('Token the address received in the swap.')),
                 signer: Signer,
+                sourceAmount: SourceAmount,
                 sourceToken: schema.Token.check(z.describe('Token the address sent into the swap.')),
             })
                 .check(z.describe('Swap inferred from token transfers through the DEX precompile. This feed entry is a summary, so per-fill details, route, and rate are not included.')),
@@ -182,7 +213,8 @@ export var schema;
             data: z
                 .object({
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and allowance amount approved for spending.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token approved for spending.')),
                 spender: Schema.Address.check(z.describe('Address allowed to spend the approved amount.')),
             })
                 .check(z.describe('A token allowance approval activity.')),
@@ -199,9 +231,15 @@ export var schema;
                 refund: z
                     .optional(schema.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.')),
@@ -266,7 +304,8 @@ export var schema;
                 .object({
                 sender: Schema.Address.check(z.describe('Address whose blocked balance was burned by policy.')),
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and amount that were burned.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token that was burned.')),
             })
                 .check(z.describe('A compliance burn of funds the receive policy blocked, distinct from a normal burn.')),
             type: z
@@ -283,7 +322,8 @@ export var schema;
                 payee: Schema.Address.check(z.describe('Address that receives payments from the channel.')),
                 payer: Schema.Address.check(z.describe('Address that funds the channel.')),
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and deposit amount locked into the channel.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token locked into the channel.')),
             })
                 .check(z.describe('A payment channel was opened and funded.')),
             type: z
@@ -298,7 +338,8 @@ export var schema;
                 .object({
                 channelId: Schema.Hex.check(z.describe('Identifier of the payment channel.')),
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and amount added to the channel deposit.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token added to the channel deposit.')),
             })
                 .check(z.describe('A payment channel deposit was topped up.')),
             type: z
@@ -315,7 +356,8 @@ export var 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: schema.Token.check(z.describe('Token and amount paid out in this settlement.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token paid out in this settlement.')),
             })
                 .check(z.describe('An incremental payment-channel settlement to the payee.')),
             type: z
@@ -333,13 +375,25 @@ export var schema;
                 payer: Schema.Address.check(z.describe('Address that funded the channel.')),
                 refund: z
                     .optional(schema.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(schema.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.describe('A payment channel was closed, paying out the payee and refunding the payer.')),
+                .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.')),
             type: z
                 .literal('channel-closed')
                 .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
@@ -371,7 +425,8 @@ export var 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: schema.Token.check(z.describe('Token and amount escrowed for the order.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token escrowed for the order.')),
                 tick: z
                     .number()
                     .check(z.int(), z.describe('Price tick the order was placed at.'), z.meta({ examples: [0] })),
@@ -402,7 +457,8 @@ export var schema;
             data: z
                 .object({
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and amount of fees distributed.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token used for the distributed fees.')),
                 validator: Schema.Address.check(z.describe('Validator that received the distributed fees.')),
             })
                 .check(z.describe('Accrued validator fees were distributed.')),
@@ -416,9 +472,11 @@ export var schema;
             ...base,
             data: z
                 .object({
-                destinationToken: schema.Token.check(z.describe('Token and amount received from the fee AMM.')),
+                destinationAmount: DestinationAmount,
+                destinationToken: schema.Token.check(z.describe('Token received from the fee AMM.')),
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and amount sent into the fee AMM.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.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.')),
@@ -434,7 +492,8 @@ export var schema;
                 .object({
                 funder: Schema.Address.check(z.describe('Address that funded the reward pool.')),
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and amount added to the reward pool.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token added to the reward pool.')),
             })
                 .check(z.describe('A token reward pool was funded.')),
             type: z
@@ -465,7 +524,8 @@ export var schema;
                 account: Schema.Address.check(z.describe('Account the access key belongs to.')),
                 publicKey: Schema.Address.check(z.describe('Public key of the access key whose limit changed.')),
                 signer: Signer,
-                sourceToken: schema.Token.check(z.describe('Token and new spending limit set for the access key.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.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
@@ -507,7 +567,8 @@ export var 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: schema.Token.check(z.describe('Token and amount the flipped order rests with.')),
+                sourceAmount: SourceAmount,
+                sourceToken: schema.Token.check(z.describe('Token the flipped order rests with.')),
                 tick: z
                     .number()
                     .check(z.int(), z.describe('Price tick the original order filled at.'), z.meta({ examples: [0] })),
@@ -1085,6 +1146,12 @@ export var schema;
     schema.Entry = z
         .union([...schema.items, schema.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. */
+    schema.Include = z
+        .enum(tokenFields)
+        .check(z.describe('Additional token fields to include in activity responses.'));
+    /** Parses comma-separated optional token fields. */
+    schema.includeQuery = Schema.includeQuery(schema.Include, 'Comma-separated token fields to include, such as `token.logoUri,token.verified`.');
     /** Schemas for the getAddressActivities operation. */
     let getAddressActivities;
     (function (getAddressActivities) {
@@ -1099,10 +1166,12 @@ export var schema;
             .strictObject({
             chainId: Schema.ChainIdQuery,
             cursor: Schema.Cursor,
+            denomination: Schema.Denomination,
             // Folding is opt-in: by default every item is returned at the root.
             group: z
                 ._default(Schema.booleanQuery(), false)
                 .check(z.describe('Set to `true` to fold consecutive items signed by the same access key on the same UTC day into `group` entries. Defaults to `false`, which returns every item separately.'), z.meta({ examples: [true] })),
+            include: schema.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.
@@ -1120,6 +1189,9 @@ export var schema;
         getAddressActivities.Response = z
             .object({
             data: z.array(schema.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.'));
@@ -1137,6 +1209,8 @@ export var schema;
         getTransactionActivities.Query = z
             .strictObject({
             chainId: Schema.ChainIdQuery,
+            denomination: Schema.Denomination,
+            include: schema.includeQuery,
             // Raw-log capture is opt-in: it can add a large `events` array to every
             // item, so the default response stays lean.
             logs: z
@@ -1153,6 +1227,9 @@ export var schema;
         getTransactionActivities.Response = z
             .object({
             data: z.array(schema.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.'));
     })(getTransactionActivities = schema.getTransactionActivities || (schema.getTransactionActivities = {}));
@@ -1308,6 +1385,11 @@ const minGroupEntries = 5;
 const maxGroupSize = 50;
 /** Token-bearing keys on an item's `data` payload, walked for enrichment. */
 const tokenKeys = ['destinationToken', 'refund', 'sourceToken'];
+const amountKeyByTokenKey = {
+    destinationToken: 'destinationAmount',
+    refund: 'refundAmount',
+    sourceToken: 'sourceAmount',
+};
 /** Builds common public activity fields from the normalized transaction hash and representative log. */
 function baseFor(options) {
     return {
@@ -1336,7 +1418,8 @@ function baseFor(options) {
  * 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 = {}) {
+    const oracle = options.fx?.oracle ?? FxOracle.ecb();
     return new Hono().get('/v1/addresses/:address/activities', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getAddressActivities.Params, {
         code: 'address_invalid',
         message: 'Check the account address and try again.',
@@ -1347,7 +1430,7 @@ export function addresses() {
         description: '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,
@@ -1374,15 +1457,13 @@ 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.
+        // Cursor pages carry current valuations and curated verification data.
         if (query.cursor !== undefined)
-            Cache.setPolicy(c, Cache.policies.immutable);
+            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, {
+            const { items: unenrichedItems, nextCursor } = await Timing.time(c, 'address_activities', () => Store.memoize(() => list(provider, {
                 address: address,
                 cursor: query.cursor,
                 group: query.group,
@@ -1394,20 +1475,26 @@ export function addresses() {
                 store: c.get('store'),
                 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.
             const data = query.group ? groupByAccessKey(items) : items;
             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);
         }
     });
@@ -1422,7 +1509,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 = {}) {
+    const oracle = options.fx?.oracle ?? FxOracle.ecb();
     return new Hono().get('/v1/transactions/:transactionHash/activities', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getTransactionActivities.Params, {
         code: 'transaction_invalid',
         message: 'Check the transaction hash and try again.',
@@ -1438,7 +1526,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.',
@@ -1448,10 +1536,8 @@ export function transactions() {
         summary: 'List transaction activities',
         tags: ['Activities'],
     }), Cache.response({
-        // 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),
@@ -1472,7 +1558,7 @@ export function transactions() {
         const query = c.req.valid('query');
         const chainId = query.chainId ?? c.get('chainId');
         try {
-            const items = await Timing.time(c, 'transaction_activities', () => Store.memoize(() => getTransactionActivities({
+            const unenrichedItems = await Timing.time(c, 'transaction_activities', () => Store.memoize(() => getTransactionActivities({
                 chainId,
                 logs: query.logs,
                 store: c.get('store'),
@@ -1483,20 +1569,30 @@ export function transactions() {
                 store: c.get('store'),
                 ttl: Ttl.seconds(15),
             }));
-            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);
-            // 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 });
-            return c.json(Response.validated(schema.getTransactionActivities.Response, { data: items }), 200);
+            // Mined activity still carries current valuations and verification data.
+            Cache.setPolicy(c, Cache.policies.metadata);
+            // 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,
+                ...(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);
         }
     });
@@ -1595,7 +1691,7 @@ export async function list(provider, options) {
         allItems.push(...page.flatMap((txGroup) => classifyGroup(txGroup, viewer, fingerprintMap, logs).map(withTitle)));
         lastGroup = page[page.length - 1];
         const enough = group
-            ? groupByAccessKey(allItems).length >= minGroupEntries
+            ? groupByAccessKeyItems(allItems).length >= minGroupEntries
             : allItems.length >= limit;
         if (enough || !hasMore)
             break;
@@ -1605,8 +1701,8 @@ export async function list(provider, options) {
     let nextCursor = 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 };
 }
 /**
@@ -3014,7 +3110,7 @@ function lowerOrNull(value) {
     const text = Value.toText(value);
     return text ? text.toLowerCase() : null;
 }
-/** Builds a stub token; `decimals`/`symbol` are filled by {@link enrichItem}. */
+/** Builds a token stub whose metadata is filled by {@link enrichItem}. */
 function token(amount, address) {
     return { address: address.toLowerCase(), amount: (amount ?? 0n).toString() };
 }
@@ -3027,48 +3123,110 @@ function collectTokens(item, set) {
             set.add(t.address.toLowerCase());
     }
 }
-/**
- * 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`.
- */
+/** Resolves TIP-20 metadata or the standard ERC-20 subset used by activity transfers. */
+function getActivityTokenMetadata(c, options) {
+    const { address, chainId } = options;
+    if (address.startsWith(tip20AddressPrefix))
+        return Tokens.getTokenMetadata(c, { address, chainId });
+    return Store.memoize(async () => {
+        const metadata = await viem_Token.getMetadata(c.get('getClient')(chainId), { token: address });
+        // ERC-20 has no currency field; its symbol is the amount's unit label.
+        return {
+            currency: metadata.symbol,
+            decimals: metadata.decimals,
+            name: metadata.name,
+            symbol: metadata.symbol,
+        };
+    }, { key: `token:erc20:v1:${chainId}:${address}:metadata`, store: c.get('store'), ttl: Ttl.minutes(1) });
+}
+/** Resolves core metadata into immutable items. Optional logo and verification sources are best-effort. */
 async function enrichTokens(c, options) {
-    const { chainId, items } = options;
+    const { chainId, denomination, include, items, oracle } = options;
     const addresses = new Set();
     for (const item of items)
         collectTokens(item, addresses);
+    // 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;
-    const resolved = await Timing.time(c, 'tokens', () => Promise.all([...addresses].map((address) => Tokens.getTokenMetadata(c, { address, chainId })
-        .then((metadata) => [address.toLowerCase(), metadata])
-        .catch(() => [address.toLowerCase(), undefined]))));
+        return { items: items, rates };
+    const includeLogoUri = include.includes('token.logoUri');
+    const includeVerified = include.includes('token.verified');
+    const resolved = await Timing.time(c, 'tokens', () => Promise.all([...addresses].map(async (address) => {
+        const [logoUri, metadata] = await Promise.all([
+            includeLogoUri
+                ? Tokens.getTokenLogo(c, { address, chainId }).catch(() => undefined)
+                : undefined,
+            getActivityTokenMetadata(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,
+            },
+        ];
+    })));
     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,
+    };
 }
-/** Spreads resolved token metadata into an item's stub tokens, in place. */
-function enrichItem(item, byAddress) {
-    const data = item.data;
+/** Returns an enriched copy of an item without mutating its cached token stubs. */
+function enrichItem(item, byAddress, valuation) {
+    const source = item.data;
+    const data = { ...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.
+            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 };
 }
 /**
  * Folds adjacent items signed by the same access key on the same UTC calendar
@@ -3076,6 +3234,10 @@ function enrichItem(item, byAddress) {
  * Must be called once over the full, timestamp-sorted item list.
  */
 export function groupByAccessKey(items) {
+    return groupByAccessKeyItems(items);
+}
+/** Groups items while preserving whether their token data has been enriched. */
+function groupByAccessKeyItems(items) {
     const entries = [];
     let currentGroup = null;
     for (const item of items) {