tapimo 0.11.0 → 0.12.0

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

@@ -22,6 +22,7 @@ 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 ZoneSelection from '../ZoneSelection.js'
 import * as Tokens from './tokens.js'
 import * as Transfers from './transfers.js'
 import * as Valuation from './valuation.js'
@@ -29,7 +30,7 @@ import * as Valuation from './valuation.js'
 /** Example transaction hash surfaced in OpenAPI docs. */
 const exampleHash = '0x4845ae2098724ab26a5d89370dce5124d044be6a5acc164afc348662de67d474'
 
-const tokenFields = ['token.logoUri', 'token.verified'] as const
+const includeFields = ['token.logoUri', 'token.verified', 'zones'] as const
 
 // TIP-20 tokens live at deterministic `0x20c0…` addresses. Other contracts
 // can emit the same `Transfer` signature but do not expose TIP-20 metadata.
@@ -202,6 +203,12 @@ export namespace schema {
    * transfer's `direction`/`memo`/`attribution`/`signer`) the resource lacks.
    */
   const base = {
+    chainId: z
+      .optional(Schema.ChainId)
+      .check(
+        z.describe('Chain id containing this activity. Returned for multi-Zone requests.'),
+        z.meta({ examples: [421700001] }),
+      ),
     perspective: z
       .enum(['incoming', 'outgoing'])
       .check(
@@ -989,9 +996,7 @@ export namespace schema {
             logoUri: z.string().check(
               z.describe('New logo URL for the token.'),
               z.meta({
-                examples: [
-                  'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
-                ],
+                examples: [Tokens.tokenExample.logoUri],
               }),
             ),
             signer: Signer,
@@ -1482,6 +1487,12 @@ export namespace schema {
   /** A folded access-key group: consecutive same-signer items on one UTC day. */
   export const Group = z
     .object({
+      chainId: z
+        .optional(Schema.ChainId)
+        .check(
+          z.describe('Chain id containing this activity group. Returned for multi-Zone requests.'),
+          z.meta({ examples: [421700001] }),
+        ),
       data: z
         .object({
           items: z.array(Item).check(z.describe('Activity items included in this group.')),
@@ -1523,15 +1534,15 @@ 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. */
+  /** Optional activity resources and selection modes. */
   export const Include = z
-    .enum(tokenFields)
-    .check(z.describe('Additional token fields to include in activity responses.'))
+    .enum(includeFields)
+    .check(z.describe('Additional activity resources and selection modes to include.'))
 
-  /** Parses comma-separated optional token fields. */
+  /** Parses comma-separated optional activity resources and selection modes. */
   export const includeQuery = Schema.includeQuery(
     Include,
-    'Comma-separated token fields to include, such as `token.logoUri,token.verified`.',
+    'Comma-separated activity options, such as `zones,token.logoUri,token.verified`.',
   )
 
   /** Schemas for the getAddressActivities operation. */
@@ -1636,6 +1647,10 @@ export namespace schema {
      */
     export const Response = z
       .object({
+        chainId: Schema.ChainId.check(
+          z.describe('Chain id containing the transaction.'),
+          z.meta({ examples: [4217] }),
+        ),
         data: z.array(Item).check(z.describe('Activity items classified from the transaction.')),
         meta: z
           .optional(schema.Meta)
@@ -1991,7 +2006,7 @@ export function addresses(options: addresses.Options = {}) {
       tags: ['Activities'],
     }),
     Cache.response<App.Environment>({
-      cacheControl: Cache.policies.feed,
+      cacheControl: Cache.policies.noStore,
       name: 'tempo-api:addresses:v1',
       key: (c) => Cache.urlKey(c, schema.getAddressActivities.Query),
     }),
@@ -2011,19 +2026,19 @@ export function addresses(options: addresses.Options = {}) {
       const { address } = c.req.valid('param')
       const query = c.req.valid('query')
 
-      // Cursor pages can carry current valuations and curated verification data.
-      if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.metadata)
+      if (!query.include.includes('zones'))
+        Cache.setPolicy(
+          c,
+          query.cursor === undefined ? Cache.policies.feed : Cache.policies.metadata,
+        )
 
       try {
         const chainId = query.chainId ?? c.get('chainId')
-        const provider = tidx({ chainId, tidx: c.get('getTidx')(chainId) })
-        const { items: unenrichedItems, nextCursor } = await Timing.time(
-          c,
-          'address_activities',
-          () =>
-            Store.memoize(
+        const listed = await Timing.time(c, 'address_activities', async () => {
+          if (!query.include.includes('zones')) {
+            const result = await Store.memoize(
               () =>
-                list(provider, {
+                list(tidx({ chainId, tidx: c.get('getTidx')(chainId) }), {
                   address: address as Hex.Hex,
                   cursor: query.cursor,
                   group: query.group,
@@ -2036,18 +2051,54 @@ export function addresses(options: addresses.Options = {}) {
                 store: c.get('store'),
                 ttl: Ttl.seconds(15),
               },
-            ),
-        )
+            )
+            return { chainId, kind: 'chain' as const, ...result }
+          }
 
-        // Build immutable token and structured amount copies from RPC metadata.
-        const { items, rates } = await enrichTokens(c, {
-          chainId,
-          denomination: query['valuation.currency'],
-          include: query.include,
-          items: unenrichedItems,
-          oracle,
+          const zoneChainIds = c.get('zoneChainIds')
+          if (!zoneChainIds) throw new Error('Inferred Zone selection was not resolved.')
+          const result = await Store.memoize(
+            () =>
+              listZones({
+                address: address as Hex.Hex,
+                cursor: query.cursor,
+                group: query.group,
+                limit: query.limit,
+                logs: query.logs,
+                providers: zoneChainIds.map((zoneChainId) => ({
+                  chainId: zoneChainId,
+                  provider: tidx({
+                    chainId: zoneChainId,
+                    tidx: c.get('getTidx')(zoneChainId),
+                  }),
+                })),
+                store: c.get('store'),
+              }),
+            {
+              key: `activities:zones:v1:${zoneChainIds.join(',')}:${address.toLowerCase()}:${query.group ?? false}:${query.logs ?? false}:${query.cursor ?? 'head'}:${query.limit}`,
+              store: c.get('store'),
+              ttl: Ttl.seconds(15),
+            },
+          )
+          return { kind: 'zones' as const, ...result }
         })
 
+        const { items, rates } =
+          listed.kind === 'zones'
+            ? await enrichZoneTokens(c, {
+                denomination: query['valuation.currency'],
+                include: query.include,
+                items: listed.items,
+                oracle,
+              })
+            : await enrichTokens(c, {
+                chainId: listed.chainId,
+                denomination: query['valuation.currency'],
+                include: query.include,
+                items: listed.items,
+                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
@@ -2056,7 +2107,7 @@ export function addresses(options: addresses.Options = {}) {
           Response.validated(schema.getAddressActivities.Response, {
             data,
             ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
-            nextCursor,
+            nextCursor: listed.nextCursor,
           }),
           200,
         )
@@ -2110,6 +2161,10 @@ export function transactions(options: transactions.Options = {}) {
             description: 'No mined transaction was found for that hash.',
             codes: ['transaction_not_found'],
           },
+          409: {
+            description: 'More than one readable Zone contains that transaction hash.',
+            codes: ['transaction_ambiguous'],
+          },
           502: 'Tempo could not read activity or token data from an upstream service.',
         },
         success: {
@@ -2142,48 +2197,123 @@ export function transactions(options: transactions.Options = {}) {
 
       const { transactionHash } = c.req.valid('param')
       const query = c.req.valid('query')
-      const chainId = query.chainId ?? c.get('chainId')
 
       try {
-        const unenrichedItems = await Timing.time(c, 'transaction_activities', () =>
-          Store.memoize(
-            () =>
-              getTransactionActivities({
-                chainId,
-                logs: query.logs,
+        const result = await Timing.time(c, 'transaction_activities', async () => {
+          const selected = await (async () => {
+            if (!query.include.includes('zones'))
+              return {
+                chainId: query.chainId ?? c.get('chainId'),
+                kind: 'selected' as const,
+                receipt: null,
+              }
+
+            const zoneChainIds = c.get('zoneChainIds')
+            if (!zoneChainIds) throw new Error('Inferred Zone selection was not resolved.')
+            // Cache only positive resolution. Missing transactions must remain
+            // visible as soon as their Zone indexer catches up.
+            const match = await Store.memoize(
+              async () => {
+                const probes: readonly ZoneSelection.uniqueMatch.Probe<TransactionReceipt>[] =
+                  await Promise.all(
+                    zoneChainIds.map(async (chainId) => {
+                      try {
+                        return {
+                          chainId,
+                          value: await getTransactionReceipt({
+                            chainId,
+                            tidx: c.get('getTidx')(chainId),
+                            transactionHash,
+                          }),
+                        }
+                      } catch (cause) {
+                        return { cause, chainId }
+                      }
+                    }),
+                  )
+                return ZoneSelection.uniqueMatch<TransactionReceipt>(probes)
+              },
+              {
+                key: `activities:zones:v1:${zoneChainIds.join(',')}:tx:${transactionHash.toLowerCase()}`,
+                shouldCache: (match) => match.kind === 'selected',
                 store: c.get('store'),
-                tidx: c.get('getTidx')(chainId),
-                transactionHash,
-              }),
+                ttl: Ttl.seconds(15),
+              },
+            )
+            if (match.kind === 'failed') {
+              c.set(
+                'providerFailures',
+                match.failures.map(({ cause, chainId }) => ({
+                  ...Tidx.providerFailure(cause),
+                  chainId,
+                })),
+              )
+              throw match.failures[0]!.cause
+            }
+            if (match.kind !== 'selected') return match
+            return { chainId: match.chainId, kind: 'selected' as const, receipt: match.value }
+          })()
+
+          if (selected.kind !== 'selected') return selected
+          const { chainId } = selected
+          const unenrichedItems = await Store.memoize(
+            () =>
+              selected.receipt === null
+                ? getTransactionActivities({
+                    chainId,
+                    logs: query.logs,
+                    store: c.get('store'),
+                    tidx: c.get('getTidx')(chainId),
+                    transactionHash,
+                  })
+                : classifyTransactionActivities({
+                    chainId,
+                    logs: query.logs,
+                    receipt: selected.receipt,
+                    store: c.get('store'),
+                    tidx: c.get('getTidx')(chainId),
+                    transactionHash,
+                  }),
             {
               key: `activities:v1:${chainId}:tx:${transactionHash.toLowerCase()}:${query.logs ?? false}`,
               store: c.get('store'),
               ttl: Ttl.seconds(15),
             },
-          ),
-        )
+          )
+          return unenrichedItems === null
+            ? ({ kind: 'not_found' } as const)
+            : ({ chainId, items: unenrichedItems, kind: 'found' } as const)
+        })
 
-        if (unenrichedItems === null)
+        if (result.kind === 'not_found')
           return Response.error(c, {
             code: 'transaction_not_found',
             message: 'Transaction not found',
             status: 404,
           })
+        if (result.kind === 'ambiguous')
+          return Response.error(c, {
+            code: 'transaction_ambiguous',
+            message: 'Transaction hash matched more than one readable Zone',
+            status: 409,
+          })
 
         // Mined activity can carry current valuations and verification data.
-        Cache.setPolicy(c, Cache.policies.metadata)
+        if (!query.include.includes('zones')) Cache.setPolicy(c, Cache.policies.metadata)
+        c.set('chainId', result.chainId)
 
         // Build immutable token and structured amount copies from RPC metadata.
         const { items, rates } = await enrichTokens(c, {
-          chainId,
+          chainId: result.chainId,
           denomination: query['valuation.currency'],
           include: query.include,
-          items: unenrichedItems,
+          items: result.items,
           oracle,
         })
 
         return c.json(
           Response.validated(schema.getTransactionActivities.Response, {
+            chainId: result.chainId,
             data: items,
             ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
           }),
@@ -2219,7 +2349,15 @@ export declare namespace transactions {
 export async function getTransactionActivities(
   options: getTransactionActivities.Options,
 ): Promise<UnenrichedItem[] | null> {
-  const { chainId, logs = false, tidx: tidxClient } = options
+  const receipt = await getTransactionReceipt(options)
+  if (!receipt) return null
+  return classifyTransactionActivities({ ...options, receipt })
+}
+
+async function getTransactionReceipt(
+  options: getTransactionReceipt.Options,
+): Promise<TransactionReceipt | null> {
+  const { chainId, tidx: tidxClient } = options
   const hash = options.transactionHash.toLowerCase()
 
   // The `receipts` table is indexed by `tx_hash`, so this point lookup needs no
@@ -2234,9 +2372,33 @@ export async function getTransactionActivities(
   const receipt = receiptResult.rows[0]
   if (!receipt) return null
 
-  const blockNum = Number(Value.toNumber(receipt['block_num']))
-  const feePayer = lowerOrNull(receipt['fee_payer'])
-  const txSender = lowerOrNull(receipt['from'])
+  return {
+    blockNum: Number(Value.toNumber(receipt['block_num'])),
+    feePayer: lowerOrNull(receipt['fee_payer']),
+    txSender: lowerOrNull(receipt['from']),
+  }
+}
+
+declare namespace getTransactionReceipt {
+  type Options = Pick<getTransactionActivities.Options, 'chainId' | 'tidx' | 'transactionHash'>
+}
+
+type TransactionReceipt = {
+  /** Block number containing the transaction. */
+  blockNum: number
+  /** Account that paid the transaction fee, when indexed. */
+  feePayer: Address.Address | null
+  /** Account that sent the transaction, when indexed. */
+  txSender: Address.Address | null
+}
+
+async function classifyTransactionActivities(
+  options: classifyTransactionActivities.Options,
+): Promise<UnenrichedItem[]> {
+  const { chainId, logs = false, receipt, tidx: tidxClient } = options
+  const hash = options.transactionHash.toLowerCase()
+  const { blockNum, feePayer, txSender } = receipt
+  const fingerprintMap_promise = Mpp.fingerprintMap({ store: options.store }).catch(() => ({}))
 
   // `logs` is sorted by block position, so a bare `tx_hash =` scans to genesis;
   // pair it with the receipt's block number (see `embedReceipts` in receipts.ts).
@@ -2269,7 +2431,7 @@ export async function getTransactionActivities(
 
   // Best-effort MPP service directory: a fetch failure yields an empty map, so
   // enrichment never blocks classification.
-  const fingerprintMap = await Mpp.fingerprintMap({ store: options.store }).catch(() => ({}))
+  const fingerprintMap = await fingerprintMap_promise
 
   // Anchor the viewer on the transaction sender: the sender initiated every
   // activity in the transaction, so `perspective` is `outgoing` and `signer`
@@ -2279,6 +2441,13 @@ export async function getTransactionActivities(
   return classifyGroup(group, viewer, fingerprintMap, logs).map(withTitle)
 }
 
+declare namespace classifyTransactionActivities {
+  type Options = getTransactionActivities.Options & {
+    /** Indexed receipt fields used to bound the log lookup. */
+    receipt: TransactionReceipt
+  }
+}
+
 export declare namespace getTransactionActivities {
   /** Options for {@link getTransactionActivities}. */
   type Options = {
@@ -2298,8 +2467,8 @@ export declare namespace getTransactionActivities {
 /**
  * Lists classified activity for an address by running the shared pipeline
  * (`groupByTx` → `classifyGroup` → `enrichItem`) over rows from a
- * {@link Provider}. Returns enriched, chain-tagged items plus the next cursor;
- * callers run {@link groupByAccessKey} over the result.
+ * {@link Provider}. Returns classified items plus the next cursor; callers run
+ * {@link groupByAccessKey} over the result.
  */
 export async function list(provider: Provider, options: list.Options): Promise<list.ReturnType> {
   const { address, cursor, group = false, limit = 20, logs = false } = options
@@ -2307,7 +2476,7 @@ export async function list(provider: Provider, options: list.Options): Promise<l
 
   // Best-effort MPP service directory: a fetch failure yields an empty map, so
   // enrichment never blocks the feed.
-  const fingerprintMap = await Mpp.fingerprintMap({ store: options.store }).catch(() => ({}))
+  const fingerprintMap_promise = Mpp.fingerprintMap({ store: options.store }).catch(() => ({}))
 
   let currentCursor: string | undefined = cursor
   const allItems: UnenrichedItem[] = []
@@ -2326,6 +2495,7 @@ export async function list(provider: Provider, options: list.Options): Promise<l
     hasMore = txGroups.length > limit
     const page = txGroups.slice(0, limit)
 
+    const fingerprintMap = await fingerprintMap_promise
     if (page.length === 0) break
 
     allItems.push(
@@ -2374,6 +2544,175 @@ export declare namespace list {
   }
 }
 
+const zoneCursorVersion = 1
+
+type ZonePageState = {
+  /** Zone chain id backing this page state. */
+  chainId: number
+  /** Whether the current buffer reaches the end of this Zone feed. */
+  exhausted: boolean
+  /** Unconsumed transaction groups already fetched from this Zone. */
+  groups: TxGroup[]
+  /** Activity data source for this Zone. */
+  provider: Provider
+}
+
+/**
+ * Lists address activity across multiple Zones in one stable timestamp-ordered
+ * feed. Its opaque cursor retains each Zone provider's native continuation.
+ */
+export async function listZones(options: listZones.Options): Promise<listZones.ReturnType> {
+  const { address, cursor, limit = 20, logs = false, providers, store } = options
+  const group = options.group ?? false
+  const orderedProviders = [...providers].sort((a, b) => a.chainId - b.chainId)
+  const chainIds = orderedProviders.map(({ chainId }) => chainId)
+  const cursors = decodeZoneCursor(cursor, chainIds)
+  const viewer = address.toLowerCase() as Address.Address
+  const fingerprintMap_promise = Mpp.fingerprintMap({ store }).catch(() => ({}))
+  const states: ZonePageState[] = orderedProviders.map(({ chainId, provider }) => ({
+    chainId,
+    exhausted: false,
+    groups: [],
+    provider,
+  }))
+  const allItems: listZones.Item[] = []
+  let hasMore = false
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await Promise.all(
+      states.map(async (state) => {
+        if (state.exhausted || state.groups.length > 0) return
+        const { rows } = await state.provider.fetchRows({
+          address: viewer,
+          cursor: cursors.get(state.chainId),
+          limit,
+        })
+        const groups = groupByTx(rows).slice(0, limit + 1)
+        state.exhausted = groups.length <= limit
+        state.groups.push(...groups)
+      }),
+    )
+    const candidates = states
+      .flatMap((state) => state.groups.map((txGroup) => ({ state, txGroup })))
+      .sort((a, b) => {
+        if (a.txGroup.blockTimestamp !== b.txGroup.blockTimestamp)
+          return b.txGroup.blockTimestamp - a.txGroup.blockTimestamp
+        if (a.state.chainId !== b.state.chainId) return a.state.chainId - b.state.chainId
+        if (a.txGroup.blockNum !== b.txGroup.blockNum)
+          return b.txGroup.blockNum - a.txGroup.blockNum
+        return b.txGroup.txIdx - a.txGroup.txIdx
+      })
+    const page = candidates.slice(0, limit)
+    const fingerprintMap = await fingerprintMap_promise
+    if (page.length === 0) break
+
+    for (const { state, txGroup } of page) {
+      state.groups.splice(state.groups.indexOf(txGroup), 1)
+      cursors.set(state.chainId, state.provider.cursorForGroup(txGroup))
+      allItems.push(
+        ...classifyGroup(txGroup, viewer, fingerprintMap, logs).map((item) => ({
+          ...withTitle(item),
+          chainId: state.chainId,
+        })),
+      )
+    }
+
+    hasMore = states.some((state) => !state.exhausted || state.groups.length > 0)
+    const enough = group
+      ? groupByAccessKeyItems(allItems).length >= minGroupEntries
+      : allItems.length >= limit
+    if (enough || !hasMore) break
+  }
+
+  // A consumed sentinel proves only that the provider may have more rows.
+  // Probe drained buffers so `nextCursor` remains the end-of-list signal.
+  await Promise.all(
+    states.map(async (state) => {
+      if (state.exhausted || state.groups.length > 0) return
+      const { rows } = await state.provider.fetchRows({
+        address: viewer,
+        cursor: cursors.get(state.chainId),
+        limit: 1,
+      })
+      const group = groupByTx(rows)[0]
+      if (group) state.groups.push(group)
+      else state.exhausted = true
+    }),
+  )
+  hasMore = states.some((state) => !state.exhausted || state.groups.length > 0)
+
+  return {
+    items: allItems,
+    nextCursor: hasMore ? encodeZoneCursor(cursors, chainIds) : null,
+  }
+}
+
+export declare namespace listZones {
+  /** One Zone activity provider. */
+  type ChainProvider = {
+    /** Zone chain id. */
+    chainId: number
+    /** Activity data source for the Zone. */
+    provider: Provider
+  }
+
+  /** A classified item tagged with its Zone chain id. */
+  type Item = UnenrichedItem & {
+    /** Zone chain id containing the activity. */
+    chainId: number
+  }
+
+  /** Options for {@link listZones}. */
+  type Options = {
+    /** Subject account address. */
+    address: Address.Address
+    /** Opaque multi-Zone cursor from a previous page. */
+    cursor?: string | undefined
+    /** Whether the caller will fold access-key items. */
+    group?: boolean | undefined
+    /** Target number of transaction groups per page. */
+    limit?: number | undefined
+    /** Attach each item's full transaction event capture. */
+    logs?: boolean | undefined
+    /** Zone providers participating in the merged feed. */
+    providers: readonly ChainProvider[]
+    /** Cache store for the MPP fingerprint-directory lookup. */
+    store: Store.Store
+  }
+
+  /** Multi-Zone classified page before token enrichment. */
+  type ReturnType = {
+    /** Timestamp-ordered, chain-tagged activity items. */
+    items: Item[]
+    /** Opaque continuation for every Zone, or null at the end. */
+    nextCursor: string | null
+  }
+}
+
+function decodeZoneCursor(cursor: string | undefined, chainIds: readonly number[]) {
+  const fields: Cursor.Field[] = ['int']
+  for (const _chainId of chainIds) fields.push('int', 'id')
+  const decoded = cursor ? Cursor.decode(cursor, fields) : undefined
+  const cursors = new Map<number, string>()
+  if (!decoded || decoded[0] !== zoneCursorVersion) return cursors
+
+  for (let index = 0; index < chainIds.length; index++) {
+    const chainId = chainIds[index]!
+    const offset = index * 2 + 1
+    if (decoded[offset] !== chainId) return new Map()
+    const value = decoded[offset + 1] as string
+    if (value !== 'head') cursors.set(chainId, value)
+  }
+  return cursors
+}
+
+function encodeZoneCursor(cursors: ReadonlyMap<number, string>, chainIds: readonly number[]) {
+  return Cursor.encode([
+    zoneCursorVersion,
+    ...chainIds.flatMap((chainId) => [chainId, cursors.get(chainId) ?? 'head']),
+  ])
+}
+
 /**
  * Creates a TIDX-backed {@link Provider} that runs three sub-queries in
  * parallel and merges them:
@@ -4521,49 +4860,63 @@ async function enrichTokens(
   for (const item of items) collectTokens(item, addresses)
   const includeLogoUri = include.includes('token.logoUri')
   const includeVerified = include.includes('token.verified')
+  const resolved_promise =
+    addresses.size > 0
+      ? 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: address.toLowerCase(), logoUri, metadata }
+            }),
+          ),
+        )
+      : undefined
   // Curated data is needed only for requested valuation or token fields.
-  const snapshot =
+  const snapshot_promise =
     addresses.size > 0 && (denomination !== undefined || includeLogoUri || includeVerified)
-      ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
-      : undefined
-  const rates = denomination
-    ? await Valuation.ratesFor(c, {
-        currencies: snapshot
-          ? [...addresses].flatMap((address) => {
-              const held = snapshot.byAddress.get(address)?.currency
-              return held === undefined ? [] : [held]
-            })
-          : [],
-        denomination,
-        oracle,
-      })
-    : undefined
-  if (addresses.size === 0) return { items: items as Item[], rates }
-
-  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)
+      ? VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+      : Promise.resolve(undefined)
+  const rates_promise = (async () => {
+    if (!denomination) return undefined
+    const snapshot = await snapshot_promise
+    return Valuation.ratesFor(c, {
+      currencies: snapshot
+        ? [...addresses].flatMap((address) => {
+            const held = snapshot.byAddress.get(address)?.currency
+            return held === undefined ? [] : [held]
+          })
+        : [],
+      denomination,
+      oracle,
+    })
+  })()
+  if (!resolved_promise) return { items: items as Item[], rates: await rates_promise }
+
+  const [resolved_raw, rates, snapshot] = await Promise.all([
+    resolved_promise,
+    rates_promise,
+    snapshot_promise,
+  ])
+  const resolved = resolved_raw.map(
+    ({ address, logoUri, metadata }) =>
+      [
+        address,
+        {
+          currency: metadata.currency,
+          decimals: metadata.decimals,
+          logoUri: includeLogoUri
+            ? (logoUri ?? snapshot?.byAddress.get(address)?.logoUri ?? metadata.logoUri)
             : 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,
-          },
-        ] as const
-      }),
-    ),
+          name: metadata.name,
+          symbol: metadata.symbol,
+          verified: includeVerified && snapshot ? snapshot.byAddress.has(address) : undefined,
+        },
+      ] as const,
   )
   const byAddress = new Map(resolved)
   return {
@@ -4584,6 +4937,54 @@ declare namespace enrichTokens {
   }
 }
 
+/** Resolves token metadata on each item's source Zone without changing feed order. */
+async function enrichZoneTokens(
+  c: Context<App.Environment>,
+  options: enrichZoneTokens.Options,
+): Promise<{ items: Item[]; rates: FxOracle.RateSet | undefined }> {
+  const byChain = new Map<number, listZones.Item[]>()
+  for (const item of options.items) {
+    const items = byChain.get(item.chainId) ?? []
+    items.push(item)
+    byChain.set(item.chainId, items)
+  }
+  const results = await Promise.all(
+    [...byChain].map(async ([chainId, items]) => ({
+      chainId,
+      ...(await enrichTokens(c, {
+        chainId,
+        denomination: options.denomination,
+        include: options.include,
+        items,
+        oracle: options.oracle,
+      })),
+    })),
+  )
+  type Bucket = { index: number; items: Item[] }
+  const buckets = new Map<number, Bucket>()
+  for (const result of results) buckets.set(result.chainId, { index: 0, items: result.items })
+  return {
+    items: options.items.map((item) => {
+      const bucket = buckets.get(item.chainId)!
+      return bucket.items[bucket.index++]!
+    }),
+    rates: results.find((result) => result.rates !== undefined)?.rates,
+  }
+}
+
+declare namespace enrichZoneTokens {
+  type Options = {
+    /** Currency the amount valuations are denominated in. */
+    denomination?: string | undefined
+    /** Optional token fields to resolve. */
+    include: readonly z.output<typeof schema.Include>[]
+    /** Chain-tagged items awaiting token enrichment. */
+    items: readonly listZones.Item[]
+    /** FX rate oracle backing amount valuation. */
+    oracle: FxOracle.Oracle
+  }
+}
+
 /** Returns an enriched copy of an item without mutating its cached token stubs. */
 function enrichItem(
   item: UnenrichedItem,
@@ -4651,6 +5052,7 @@ export function groupByAccessKey(items: Item[]): Entry[] {
 }
 
 type GroupableItem = {
+  chainId?: number | undefined
   data: object
   id: string
   perspective: 'incoming' | 'outgoing'
@@ -4660,6 +5062,7 @@ type GroupableItem = {
 type GroupedItem<item extends GroupableItem> =
   | item
   | {
+      chainId?: number | undefined
       data: { items: item[]; signer: Address.Address }
       id: string
       perspective: 'incoming' | 'outgoing'
@@ -4678,6 +5081,7 @@ function groupByAccessKeyItems<item extends GroupableItem>(items: item[]): Group
     if (itemSigner !== 'self') {
       if (
         currentGroup &&
+        currentGroup.items[0]!.chainId === item.chainId &&
         Address.isEqual(currentGroup.signer, itemSigner) &&
         sameCalendarDay(currentGroup.items[0]!.timestamp, item.timestamp)
       ) {
@@ -4717,6 +5121,7 @@ function flushGroup<item extends GroupableItem>(group: {
   const firstItem = group.items[0]!
   const lastItem = group.items[group.items.length - 1]!
   return {
+    ...(firstItem.chainId === undefined ? {} : { chainId: firstItem.chainId }),
     data: { items: group.items, signer: group.signer },
     perspective: firstItem.perspective,
     id: `${firstItem.id}..${lastItem.id}:${group.items.length}`,