tapimo 0.0.0 → 0.0.2

package/src/apps/activities.ts

@@ -0,0 +1,3934 @@
+import { Hono, type Context } from 'hono'
+import { Address, Hex } from 'ox'
+import { type Log, parseEventLogs, zeroAddress } from 'viem'
+import { Abis, Addresses } from 'viem/tempo'
+import * as z from 'zod/mini'
+
+import type * as App from '../App.js'
+import * as Auth from '../internal/Auth.js'
+import * as Cache from '../internal/Cache.js'
+import * as Cursor from '../internal/Cursor.js'
+import * as Mpp from '../internal/Mpp.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Response from '../internal/Response.js'
+import * as Schema from '../internal/Schema.js'
+import * as Store from '../internal/Store.js'
+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 Tokens from './tokens.js'
+import * as Transfers from './transfers.js'
+
+/** Example transaction hash surfaced in OpenAPI docs. */
+const exampleHash = '0x4845ae2098724ab26a5d89370dce5124d044be6a5acc164afc348662de67d474'
+
+/** Zod schemas owned by the activity handlers. */
+export namespace schema {
+  /** A signer: the literal `self`, or the access-key address that signed. */
+  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.
+   */
+  export const 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).
+   */
+  export const Transfer = z
+    .object({
+      attribution: z
+        .optional(z.string())
+        .check(
+          z.describe(
+            'MPP service name matched from the transfer memo, when Tempo recognizes the fingerprint.',
+          ),
+          z.meta({ examples: ['Acme Payments'] }),
+        ),
+      blockNumber: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Block number where this transfer was included.'),
+          z.meta({ examples: [12345678] }),
+        ),
+      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.',
+          ),
+        ),
+      direction: z
+        .enum(['in', 'out'])
+        .check(
+          z.describe(
+            'The address’s side of the transfer: `in` means received, and `out` means sent.',
+          ),
+        ),
+      memo: z
+        .optional(z.string())
+        .check(z.describe('Text memo attached to the transfer, when one was provided.'), z.meta({ examples: ['Invoice #1234'] })), // prettier-ignore
+      recipient: Schema.Address.check(z.describe('Address that received the transfer.')),
+      sender: Schema.Address.check(z.describe('Address that sent the transfer.')),
+      signer: z
+        .optional(Signer)
+        .check(
+          z.describe(
+            '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.')),
+      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.'))
+
+  /**
+   * One transaction log, decoded into a known Tempo event when possible. The
+   * raw fields (`address`/`data`/`logIndex`/`topics`) are always present so no
+   * log is hidden; the decoded fields (`args`/`eventName`/`title`) are present
+   * only when the log matched a known `viem/tempo` ABI.
+   */
+  const event = z
+    .object({
+      address: Schema.Address.check(z.describe('Contract address that emitted the log.')),
+      args: z
+        .optional(z.record(z.string(), z.unknown()))
+        .check(
+          z.describe(
+            'Decoded event arguments keyed by parameter name, present when the log matched a known ABI. Integer values are decimal strings.',
+          ),
+        ),
+      data: Schema.Hex.check(z.describe('Unindexed log data as a hex string (`0x` when empty).')),
+      eventName: z
+        .optional(z.string())
+        .check(z.describe('Event name decoded from the `viem/tempo` ABIs, present when the log matched a known ABI.'), z.meta({ examples: ['Transfer'] })), // prettier-ignore
+      logIndex: z
+        .number()
+        .check(z.int(), z.nonnegative(), z.describe('Log index for this log within the block.'), z.meta({ examples: [4] })), // prettier-ignore
+      title: z
+        .optional(z.string())
+        .check(z.describe('Human-readable label for the decoded event, present when the log matched a known ABI.'), z.meta({ examples: ['Token transferred'] })), // prettier-ignore
+      topics: z
+        .array(Schema.Hash)
+        .check(z.describe('Raw log topics; the first topic is the event signature hash.')),
+    })
+    .check(
+      z.describe(
+        'One transaction log. Decoded fields (`eventName`/`args`/`title`) are present when it matched a known Tempo ABI; otherwise only the raw fields are set.',
+      ),
+    )
+
+  /**
+   * Fields shared by every activity item. `transactionHash`/`timestamp` identify and sort
+   * the entry; `data` carries the type-specific payload — shaped like the
+   * matching API resource where one exists, plus any feed-only fields (e.g. a
+   * transfer's `direction`/`memo`/`attribution`/`signer`) the resource lacks.
+   */
+  const base = {
+    perspective: z
+      .enum(['incoming', 'outgoing'])
+      .check(
+        z.describe(
+          'Your role in the transaction: `outgoing` when you sent or paid for it, `incoming` when it happened to you (someone else initiated it). For a `transfer`, `data.direction` is the finer-grained token-flow view.',
+        ),
+      ),
+    events: z
+      .optional(z.array(event))
+      .check(
+        z.describe(
+          'Every log in the transaction, decoded when possible, so nothing is hidden. Returned only when the request sets `logs=true`, except on `unknown` items where it is always present.',
+        ),
+      ),
+    id: z.string().check(
+      z.describe(
+        'Stable activity ID built from the transaction hash and log index (`${transactionHash}-${logIndex}`).',
+      ),
+      z.meta({
+        examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-3'],
+      }),
+    ),
+    logIndex: z
+      .number()
+      .check(
+        z.int(),
+        z.nonnegative(),
+        z.describe('Log index for this activity within the block.'),
+        z.meta({ examples: [3] }),
+      ),
+    timestamp: z
+      .iso.datetime()
+      .check(z.describe('Block timestamp as an ISO 8601 string.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })), // prettier-ignore
+    title: z
+      .string()
+      .check(
+        z.describe(
+          'Human-readable label for the activity `type`, suitable for display in a feed. Past-tense, sentence case (e.g. `Token transferred`, `Tokens swapped`, `Burn blocked`).',
+        ),
+        z.meta({ examples: ['Token transferred'] }),
+      ),
+    transactionHash: Schema.Hash.check(z.describe('Transaction hash for this activity.')),
+  }
+
+  /** The classified activity item variants (discriminated by `type`). */
+  export const items = [
+    z
+      .object({
+        ...base,
+        data: Transfer.check(
+          z.describe(
+            'Transfer details, using the `/transfers` shape plus feed-only fields such as direction and signer.',
+          ),
+        ),
+        type: z
+          .literal('transfer')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token transferred' })),
+    z
+      .object({
+        ...base,
+        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.')),
+          })
+          .check(z.describe('A token mint activity.')),
+        type: z
+          .literal('mint')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token minted' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .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.')),
+          })
+          .check(z.describe('A token burn activity.')),
+        type: z
+          .literal('burn')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token burned' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            destinationToken: Token.check(z.describe('Token the address received in the swap.')),
+            signer: Signer,
+            sourceToken: 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.',
+            ),
+          ),
+        type: z
+          .literal('swap')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Tokens swapped' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            signer: Signer,
+            sourceToken: Token.check(
+              z.describe('Token and allowance amount approved for spending.'),
+            ),
+            spender: Schema.Address.check(
+              z.describe('Address allowed to spend the approved amount.'),
+            ),
+          })
+          .check(z.describe('A token allowance approval activity.')),
+        type: z
+          .literal('approval')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Allowance approved' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            refund: z
+              .optional(Token)
+              .check(z.describe('Token refunded to the address when the session closed, if any.')),
+            signer: Signer,
+          })
+          .check(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.')),
+      })
+      .check(z.meta({ title: 'Session closed' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            account: Schema.Address.check(
+              z.describe('Account this access key was authorized for.'),
+            ),
+            expiry: z
+              .number()
+              .check(z.int(), z.describe('Access-key expiration time as a Unix timestamp.'), z.meta({ examples: [1735689600] })), // prettier-ignore
+            publicKey: Schema.Address.check(
+              z.describe('Public key for the authorized access key.'),
+            ),
+            signatureType: z
+              .number()
+              .check(
+                z.int(),
+                z.describe('Signature type used by the access key.'),
+                z.meta({ examples: [0] }),
+              ),
+          })
+          .check(z.describe('An access key was created for the account.')),
+        type: z
+          .literal('access-key-created')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Access key created' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            account: Schema.Address.check(z.describe('Account this access key was revoked from.')),
+            publicKey: Schema.Address.check(z.describe('Public key for the revoked access key.')),
+          })
+          .check(z.describe('An access key was revoked from the account.')),
+        type: z
+          .literal('access-key-revoked')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Access key revoked' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            address: Schema.Address.check(z.describe('Contract address of the new TIP-20 token.')),
+            currency: z.string().check(z.describe('Display currency for the token, such as USD.'), z.meta({ examples: ['USD'] })), // prettier-ignore
+            name: z.string().check(z.describe('Human-readable token name.'), z.meta({ examples: ['Tempo USD'] })), // prettier-ignore
+            symbol: z
+              .string()
+              .check(z.describe('Token ticker symbol.'), z.meta({ examples: ['TUSD'] })),
+          })
+          .check(z.describe('A new TIP-20 token was created.')),
+        type: z
+          .literal('token-created')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token created' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            sender: Schema.Address.check(
+              z.describe('Address whose blocked balance was burned by policy.'),
+            ),
+            signer: Signer,
+            sourceToken: Token.check(z.describe('Token and amount that were burned.')),
+          })
+          .check(
+            z.describe(
+              'A compliance burn of funds the receive policy blocked, distinct from a normal burn.',
+            ),
+          ),
+        type: z
+          .literal('burn-blocked')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Burn blocked' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            channelId: Schema.Hex.check(z.describe('Identifier of the payment channel.')),
+            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: Token.check(
+              z.describe('Token and deposit amount locked into the channel.'),
+            ),
+          })
+          .check(z.describe('A payment channel was opened and funded.')),
+        type: z
+          .literal('channel-opened')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Channel opened' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .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.')),
+          })
+          .check(z.describe('A payment channel deposit was topped up.')),
+        type: z
+          .literal('channel-funded')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Channel funded' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            channelId: Schema.Hex.check(z.describe('Identifier of the payment channel.')),
+            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.')),
+          })
+          .check(z.describe('An incremental payment-channel settlement to the payee.')),
+        type: z
+          .literal('channel-settled')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Channel settled' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            channelId: Schema.Hex.check(z.describe('Identifier of the payment channel.')),
+            payee: Schema.Address.check(
+              z.describe('Address that receives payments from the channel.'),
+            ),
+            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.')),
+            signer: Signer,
+            sourceToken: z
+              .optional(Token)
+              .check(z.describe('Token and final amount 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.',
+            ),
+          ),
+        type: z
+          .literal('channel-closed')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Channel closed' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            channelId: Schema.Hex.check(z.describe('Identifier of the payment channel.')),
+            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,
+          })
+          .check(z.describe('A pending payment-channel close request was cancelled.')),
+        type: z
+          .literal('channel-close-cancelled')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Channel close cancelled' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            orderId: Schema.DecimalString.check(z.describe('Identifier of the DEX order.')),
+            side: z
+              .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.')),
+            tick: z
+              .number()
+              .check(
+                z.int(),
+                z.describe('Price tick the order was placed at.'),
+                z.meta({ examples: [0] }),
+              ),
+          })
+          .check(z.describe('A limit order was placed on the stablecoin DEX.')),
+        type: z
+          .literal('order-placed')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Order placed' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            orderId: Schema.DecimalString.check(
+              z.describe('Identifier of the cancelled DEX order.'),
+            ),
+            signer: Signer,
+          })
+          .check(z.describe('A DEX order was cancelled.')),
+        type: z
+          .literal('order-cancelled')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Order cancelled' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            signer: Signer,
+            sourceToken: Token.check(z.describe('Token and amount of fees distributed.')),
+            validator: Schema.Address.check(
+              z.describe('Validator that received the distributed fees.'),
+            ),
+          })
+          .check(z.describe('Accrued validator fees were distributed.')),
+        type: z
+          .literal('fees-distributed')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Fees distributed' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            destinationToken: Token.check(
+              z.describe('Token and amount received from the fee AMM.'),
+            ),
+            signer: Signer,
+            sourceToken: Token.check(z.describe('Token and amount 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.')),
+        type: z
+          .literal('fee-rebalance-swap')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Fees rebalanced' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .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.')),
+          })
+          .check(z.describe('A token reward pool was funded.')),
+        type: z
+          .literal('reward-distributed')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Reward distributed' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            holder: Schema.Address.check(z.describe('Holder whose rewards were redirected.')),
+            recipient: Schema.Address.check(
+              z.describe('Address that now receives the holder’s rewards.'),
+            ),
+            signer: Signer,
+          })
+          .check(z.describe('A holder redirected where their token rewards are paid.')),
+        type: z
+          .literal('reward-recipient-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Reward recipient set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            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: Token.check(
+              z.describe('Token and new spending limit set for the access key.'),
+            ),
+          })
+          .check(z.describe('An access key’s per-token spending limit was updated.')),
+        type: z
+          .literal('spending-limit-updated')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Spending limit updated' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            amountFilled: Schema.DecimalString.check(
+              z.describe('Amount filled, in the token’s smallest unit.'),
+            ),
+            maker: Schema.Address.check(z.describe('Maker whose resting order was filled.')),
+            orderId: Schema.DecimalString.check(z.describe('Identifier of the filled DEX order.')),
+            partialFill: z
+              .boolean()
+              .check(
+                z.describe('Whether the order was only partially filled.'),
+                z.meta({ examples: [true] }),
+              ),
+            signer: Signer,
+            taker: Schema.Address.check(z.describe('Taker that filled the order.')),
+          })
+          .check(z.describe('A resting DEX order was filled by a taker.')),
+        type: z
+          .literal('order-filled')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Order filled' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            flipTick: z
+              .number()
+              .check(
+                z.int(),
+                z.describe('Price tick the flipped order was placed at.'),
+                z.meta({ examples: [0] }),
+              ),
+            maker: Schema.Address.check(z.describe('Maker the order belongs to.')),
+            orderId: Schema.DecimalString.check(z.describe('Identifier of the DEX order.')),
+            side: z
+              .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.')),
+            tick: z
+              .number()
+              .check(
+                z.int(),
+                z.describe('Price tick the original order filled at.'),
+                z.meta({ examples: [0] }),
+              ),
+          })
+          .check(z.describe('A flip order was rotated to the opposite side after filling.')),
+        type: z
+          .literal('order-flipped')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Order flipped' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            base: Schema.Address.check(z.describe('Base token of the new trading pair.')),
+            key: Schema.Hex.check(z.describe('Identifier of the trading pair.')),
+            quote: Schema.Address.check(z.describe('Quote token of the new trading pair.')),
+            signer: Signer,
+          })
+          .check(z.describe('A new trading pair was created on the stablecoin DEX.')),
+        type: z
+          .literal('pair-created')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Trading pair created' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            paused: z
+              .boolean()
+              .check(z.describe('Whether the token is now paused.'), z.meta({ examples: [true] })),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that changed the pause state.')),
+          })
+          .check(z.describe('A TIP-20 token was paused or unpaused.')),
+        type: z
+          .literal('token-pause-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token pause set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            signer: Signer,
+            supplyCap: Schema.DecimalString.check(
+              z.describe('New maximum total supply, in the token’s smallest unit.'),
+            ),
+            updater: Schema.Address.check(z.describe('Address that changed the supply cap.')),
+          })
+          .check(z.describe('A TIP-20 token’s supply cap was changed.')),
+        type: z
+          .literal('token-supply-cap-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token supply cap set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            policyId: Schema.DecimalString.check(
+              z.describe('Identifier of the transfer policy now linked to the token.'),
+            ),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that linked the transfer policy.')),
+          })
+          .check(z.describe('A TIP-20 token’s transfer policy was changed.')),
+        type: z
+          .literal('token-transfer-policy-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token transfer policy set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            quoteToken: Schema.Address.check(z.describe('Token now used as the quote token.')),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that changed the quote token.')),
+          })
+          .check(z.describe('A TIP-20 token’s quote token was changed.')),
+        type: z
+          .literal('token-quote-token-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token quote token set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            nextQuoteToken: Schema.Address.check(
+              z.describe('Token queued to become the next quote token.'),
+            ),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that queued the next quote token.')),
+          })
+          .check(z.describe('A TIP-20 token’s next quote token was queued.')),
+        type: z
+          .literal('token-next-quote-token-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token next quote token set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            logoUri: z.string().check(
+              z.describe('New logo URL for the token.'),
+              z.meta({
+                examples: [
+                  'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
+                ],
+              }),
+            ),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that changed the logo.')),
+          })
+          .check(z.describe('A TIP-20 token’s logo URI was changed.')),
+        type: z
+          .literal('token-logo-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Token logo set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            account: Schema.Address.check(z.describe('Account whose role membership changed.')),
+            granted: z
+              .boolean()
+              .check(
+                z.describe('Whether the role was granted (`true`) or revoked (`false`).'),
+                z.meta({ examples: [true] }),
+              ),
+            role: Schema.Hex.check(z.describe('Identifier of the role (a `bytes32` role hash).')),
+            sender: Schema.Address.check(z.describe('Address that made the role change.')),
+            signer: Signer,
+          })
+          .check(z.describe('A role was granted to or revoked from an account.')),
+        type: z
+          .literal('role-membership-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Role membership set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            newAdminRole: Schema.Hex.check(z.describe('Identifier of the new admin role.')),
+            role: Schema.Hex.check(z.describe('Identifier of the role whose admin changed.')),
+            sender: Schema.Address.check(z.describe('Address that changed the admin role.')),
+            signer: Signer,
+          })
+          .check(z.describe('A role’s admin role was changed.')),
+        type: z
+          .literal('role-admin-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Role admin set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            signer: Signer,
+            token: Schema.Address.check(z.describe('Token the user will pay fees in.')),
+            user: Schema.Address.check(z.describe('Address whose fee token was set.')),
+          })
+          .check(z.describe('An account’s fee-payment token was set.')),
+        type: z
+          .literal('fee-user-token-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Fee user token set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            signer: Signer,
+            token: Schema.Address.check(z.describe('Token the validator will be paid fees in.')),
+            validator: Schema.Address.check(z.describe('Validator whose payout token was set.')),
+          })
+          .check(z.describe('A validator’s fee-payout token was set.')),
+        type: z
+          .literal('fee-validator-token-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Fee validator token set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            policyId: Schema.DecimalString.check(z.describe('Identifier of the created policy.')),
+            policyType: z
+              .number()
+              .check(z.int(), z.describe('Numeric policy type.'), z.meta({ examples: [0] })),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that created the policy.')),
+          })
+          .check(z.describe('A TIP-403 compliance policy was created.')),
+        type: z
+          .literal('policy-created')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Policy created' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            admin: Schema.Address.check(z.describe('New admin of the policy.')),
+            policyId: Schema.DecimalString.check(z.describe('Identifier of the policy.')),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that changed the policy admin.')),
+          })
+          .check(z.describe('A TIP-403 policy’s admin was changed.')),
+        type: z
+          .literal('policy-admin-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Policy admin set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            account: Schema.Address.check(z.describe('Account whose whitelist status changed.')),
+            allowed: z
+              .boolean()
+              .check(
+                z.describe('Whether the account is now whitelisted.'),
+                z.meta({ examples: [true] }),
+              ),
+            policyId: Schema.DecimalString.check(z.describe('Identifier of the policy.')),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that changed the whitelist.')),
+          })
+          .check(z.describe('An account’s whitelist status on a policy was changed.')),
+        type: z
+          .literal('whitelist-updated')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Whitelist updated' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            account: Schema.Address.check(z.describe('Account whose blacklist status changed.')),
+            policyId: Schema.DecimalString.check(z.describe('Identifier of the policy.')),
+            restricted: z
+              .boolean()
+              .check(
+                z.describe('Whether the account is now blacklisted.'),
+                z.meta({ examples: [true] }),
+              ),
+            signer: Signer,
+            updater: Schema.Address.check(z.describe('Address that changed the blacklist.')),
+          })
+          .check(z.describe('An account’s blacklist status on a policy was changed.')),
+        type: z
+          .literal('blacklist-updated')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Blacklist updated' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            creator: Schema.Address.check(z.describe('Address that created the compound policy.')),
+            mintRecipientPolicyId: Schema.DecimalString.check(
+              z.describe('Sub-policy applied to mint recipients.'),
+            ),
+            policyId: Schema.DecimalString.check(
+              z.describe('Identifier of the created compound policy.'),
+            ),
+            recipientPolicyId: Schema.DecimalString.check(
+              z.describe('Sub-policy applied to recipients.'),
+            ),
+            senderPolicyId: Schema.DecimalString.check(
+              z.describe('Sub-policy applied to senders.'),
+            ),
+            signer: Signer,
+          })
+          .check(z.describe('A TIP-403 compound policy was created from sub-policies.')),
+        type: z
+          .literal('compound-policy-created')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Compound policy created' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            masterAddress: Schema.Address.check(
+              z.describe('Address of the registered master contract.'),
+            ),
+            masterId: Schema.Hex.check(
+              z.describe('Identifier of the master contract (a `bytes4` selector).'),
+            ),
+            signer: Signer,
+          })
+          .check(z.describe('A master contract was registered in the address registry.')),
+        type: z
+          .literal('master-registered')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Master registered' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            account: Schema.Address.check(z.describe('Account whose nonce advanced.')),
+            nonce: Schema.DecimalString.check(z.describe('New nonce value.')),
+            nonceKey: Schema.DecimalString.check(z.describe('Nonce key that was advanced.')),
+            signer: Signer,
+          })
+          .check(z.describe('An account or access-key nonce was advanced.')),
+        type: z
+          .literal('nonce-incremented')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Nonce incremented' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            account: Schema.Address.check(z.describe('Account the witness belongs to.')),
+            signer: Signer,
+            witness: Schema.Hex.check(
+              z.describe('Witness commitment recorded for the key authorization.'),
+            ),
+          })
+          .check(z.describe('A key-authorization witness was recorded.')),
+        type: z
+          .literal('key-authorization-witness')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Key authorization witnessed' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            account: Schema.Address.check(z.describe('Account the witness belonged to.')),
+            signer: Signer,
+            witness: Schema.Hex.check(z.describe('Witness commitment that was consumed.')),
+          })
+          .check(z.describe('A key-authorization witness was consumed.')),
+        type: z
+          .literal('key-authorization-witness-burned')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Key authorization witness burned' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            egress: z
+              .string()
+              .check(
+                z.describe('Egress network endpoint.'),
+                z.meta({ examples: ['https://validator.example.com:8443'] }),
+              ),
+            feeRecipient: Schema.Address.check(z.describe('Validator fee recipient address.')),
+            index: Schema.DecimalString.check(z.describe('Validator index.')),
+            ingress: z
+              .string()
+              .check(
+                z.describe('Ingress network endpoint.'),
+                z.meta({ examples: ['https://validator.example.com:8443'] }),
+              ),
+            publicKey: Schema.Hex.check(z.describe('Validator public key.')),
+            signer: Signer,
+            validator: Schema.Address.check(z.describe('Validator address.')),
+          })
+          .check(z.describe('A validator was added to the validator set.')),
+        type: z
+          .literal('validator-added')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Validator added' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            index: Schema.DecimalString.check(z.describe('Validator index.')),
+            signer: Signer,
+            validator: Schema.Address.check(z.describe('Validator address.')),
+          })
+          .check(z.describe('A validator was deactivated.')),
+        type: z
+          .literal('validator-deactivated')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Validator deactivated' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            caller: Schema.Address.check(z.describe('Address that rotated the validator.')),
+            deactivatedIndex: Schema.DecimalString.check(
+              z.describe('Index of the deactivated validator entry.'),
+            ),
+            egress: z
+              .string()
+              .check(
+                z.describe('Egress network endpoint.'),
+                z.meta({ examples: ['https://validator.example.com:8443'] }),
+              ),
+            index: Schema.DecimalString.check(z.describe('New validator index.')),
+            ingress: z
+              .string()
+              .check(
+                z.describe('Ingress network endpoint.'),
+                z.meta({ examples: ['https://validator.example.com:8443'] }),
+              ),
+            newPublicKey: Schema.Hex.check(z.describe('New validator public key.')),
+            oldPublicKey: Schema.Hex.check(z.describe('Previous validator public key.')),
+            signer: Signer,
+            validator: Schema.Address.check(z.describe('Validator address.')),
+          })
+          .check(z.describe('A validator’s keys and endpoints were rotated.')),
+        type: z
+          .literal('validator-rotated')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Validator rotated' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            caller: Schema.Address.check(z.describe('Address that changed the fee recipient.')),
+            feeRecipient: Schema.Address.check(z.describe('New validator fee recipient.')),
+            index: Schema.DecimalString.check(z.describe('Validator index.')),
+            signer: Signer,
+          })
+          .check(z.describe('A validator’s fee recipient was changed.')),
+        type: z
+          .literal('validator-fee-recipient-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Validator fee recipient set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            caller: Schema.Address.check(z.describe('Address that changed the endpoints.')),
+            egress: z
+              .string()
+              .check(
+                z.describe('Egress network endpoint.'),
+                z.meta({ examples: ['https://validator.example.com:8443'] }),
+              ),
+            index: Schema.DecimalString.check(z.describe('Validator index.')),
+            ingress: z
+              .string()
+              .check(
+                z.describe('Ingress network endpoint.'),
+                z.meta({ examples: ['https://validator.example.com:8443'] }),
+              ),
+            signer: Signer,
+          })
+          .check(z.describe('A validator’s network endpoints were changed.')),
+        type: z
+          .literal('validator-ip-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Validator IP set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            caller: Schema.Address.check(z.describe('Address that transferred ownership.')),
+            index: Schema.DecimalString.check(z.describe('Validator index.')),
+            newAddress: Schema.Address.check(z.describe('New validator owner address.')),
+            oldAddress: Schema.Address.check(z.describe('Previous validator owner address.')),
+            signer: Signer,
+          })
+          .check(z.describe('A validator’s owner address was changed.')),
+        type: z
+          .literal('validator-ownership-transferred')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Validator ownership transferred' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            newOwner: Schema.Address.check(z.describe('New contract owner.')),
+            oldOwner: Schema.Address.check(z.describe('Previous contract owner.')),
+            signer: Signer,
+          })
+          .check(z.describe('Contract ownership was transferred.')),
+        type: z
+          .literal('ownership-transferred')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Ownership transferred' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            index: Schema.DecimalString.check(z.describe('Validator index.')),
+            publicKey: Schema.Hex.check(z.describe('Validator public key.')),
+            signer: Signer,
+            validator: Schema.Address.check(z.describe('Validator address.')),
+          })
+          .check(z.describe('A validator was migrated.')),
+        type: z
+          .literal('validator-migrated')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Validator migrated' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            index: Schema.DecimalString.check(z.describe('Validator index.')),
+            publicKey: Schema.Hex.check(z.describe('Validator public key.')),
+            signer: Signer,
+            validator: Schema.Address.check(z.describe('Validator address.')),
+          })
+          .check(z.describe('A validator migration was skipped.')),
+        type: z
+          .literal('validator-migration-skipped')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Validator migration skipped' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            nextEpoch: Schema.DecimalString.check(
+              z.describe('Epoch the rotation is scheduled for.'),
+            ),
+            previousEpoch: Schema.DecimalString.check(z.describe('Previous rotation epoch.')),
+            signer: Signer,
+          })
+          .check(z.describe('A network-identity rotation epoch was scheduled.')),
+        type: z
+          .literal('network-identity-rotation-epoch-set')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Network identity rotation epoch set' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({
+            height: Schema.DecimalString.check(z.describe('Block height at initialization.')),
+            signer: Signer,
+          })
+          .check(z.describe('A contract was initialized.')),
+        type: z
+          .literal('initialized')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Initialized' })),
+    z
+      .object({
+        ...base,
+        data: z
+          .object({ signer: Signer })
+          .check(
+            z.describe(
+              'A transaction the address sent or paid for that Tempo could not classify into a known activity type. The decoded and raw logs are surfaced in the top-level `events` array.',
+            ),
+          ),
+        type: z
+          .literal('unknown')
+          .check(z.describe('Activity type that tells you which `data` shape this entry uses.')),
+      })
+      .check(z.meta({ title: 'Unknown' })),
+  ] as const
+
+  /** A single classified activity item. */
+  export const Item = z
+    .union(items)
+    .check(z.describe('One classified activity item in the address feed.'))
+
+  /** A folded access-key group: consecutive same-signer items on one UTC day. */
+  export const Group = z
+    .object({
+      data: z
+        .object({
+          items: z.array(Item).check(z.describe('Activity items included in this group.')),
+          signer: Schema.Address.check(
+            z.describe('Access-key address that signed every item in the group.'),
+          ),
+        })
+        .check(z.describe('Grouped activity entries folded together for readability.')),
+      perspective: z
+        .enum(['incoming', 'outgoing'])
+        .check(
+          z.describe(
+            'The shared perspective of the items in this group (see an item’s `perspective`).',
+          ),
+        ),
+      id: z.string().check(
+        z.describe('Stable group ID derived from the activity IDs inside the group.'),
+        z.meta({
+          examples: [
+            '0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-3..0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-7:5',
+          ],
+        }),
+      ),
+      timestamp: z
+        .iso.datetime()
+        .check(z.describe('Timestamp of the first item in the group, as an ISO 8601 string.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })), // prettier-ignore
+      title: z
+        .literal('Group')
+        .check(z.describe('Human-readable label for this entry, suitable for display in a feed.')),
+      type: z.literal('group'),
+    })
+    .check(
+      z.meta({ title: 'Group' }),
+      z.describe('A group of consecutive activity items signed by the same access key.'),
+    )
+
+  /** A single activity item, or a folded access-key group. */
+  export const Entry = z
+    .union([...items, Group])
+    .check(z.describe('Either one activity item, or a grouped set of access-key activity items.'))
+
+  /** Schemas for the getAddressActivities operation. */
+  export namespace getAddressActivities {
+    /** Path parameters for address activity requests. */
+    export const Params = z
+      .object({
+        address: Schema.Address.check(
+          z.describe('Account address whose activity you want to list.'),
+        ),
+      })
+      .check(z.describe('Path parameters for the address activity request.'))
+
+    /** Query parameters for address activity requests. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        cursor: Schema.Cursor,
+        // 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] }),
+          ),
+        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.
+        logs: z
+          ._default(Schema.booleanQuery(), false)
+          .check(
+            z.describe(
+              'Set to `true` to attach each item’s full transaction log set (decoded when possible) as a top-level `events` array, so no co-located log is hidden. Defaults to `false`. `unknown` items always include it.',
+            ),
+            z.meta({ examples: [true] }),
+          ),
+      })
+      .check(
+        z.describe(
+          'Query parameters for the address activity request. This feed uses cursor pagination only because activity classification can fold a variable number of rows into each entry, so positional `page` pagination would not be stable.',
+        ),
+      )
+
+    /**
+     * Page of classified activity. Mirrors the wallet activity feed: a
+     * newest-first list of `data` entries (items, or access-key groups when
+     * `group=true`) plus the root `nextCursor` pagination field shared with
+     * other list endpoints.
+     */
+    export const Response = z
+      .object({
+        data: z.array(Entry).check(z.describe('Activity feed entries for the address.')),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of human-readable activity for the address.'))
+  }
+
+  /** Schemas for the getTransactionActivities operation. */
+  export namespace getTransactionActivities {
+    /** Path parameters for transaction activity requests. */
+    export const Params = z
+      .object({
+        transactionHash: Schema.hash(exampleHash).check(
+          z.describe(
+            'A 32-byte hash, `0x`-prefixed and returned in lowercase, that identifies the transaction whose activity you want to list.',
+          ),
+        ),
+      })
+      .check(z.describe('Path parameters for the transaction activity request.'))
+
+    /** Query parameters for transaction activity requests. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        // Raw-log capture is opt-in: it can add a large `events` array to every
+        // item, so the default response stays lean.
+        logs: z
+          ._default(Schema.booleanQuery(), false)
+          .check(
+            z.describe(
+              'Set to `true` to attach each item’s full transaction log set (decoded when possible) as a top-level `events` array, so no co-located log is hidden. Defaults to `false`. `unknown` items always include it.',
+            ),
+            z.meta({ examples: [true] }),
+          ),
+      })
+      .check(z.describe('Query parameters for the transaction activity request.'))
+
+    /**
+     * The classified activity for one transaction: a list of `data` items
+     * (usually one headline item, occasionally more) describing what the
+     * transaction did onchain. Unpaginated — a single transaction is finite —
+     * so there is no `nextCursor`.
+     */
+    export const Response = z
+      .object({
+        data: z.array(Item).check(z.describe('Activity items classified from the transaction.')),
+      })
+      .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}). */
+export type Token = z.output<typeof schema.Token>
+
+/** A single classified activity item (derived from {@link schema.Item}). */
+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>
+
+/**
+ * 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']]
+
+/**
+ * Human-readable label for each activity {@link Item.type}, mirroring the per-variant
+ * OpenAPI schema titles. Used to stamp {@link Item.title} during {@link list}.
+ */
+const titleByType: Record<Item['type'], string> = {
+  approval: 'Allowance approved',
+  'access-key-created': 'Access key created',
+  'access-key-revoked': 'Access key revoked',
+  'blacklist-updated': 'Blacklist updated',
+  burn: 'Token burned',
+  'burn-blocked': 'Burn blocked',
+  'channel-close-cancelled': 'Channel close cancelled',
+  'channel-closed': 'Channel closed',
+  'channel-funded': 'Channel funded',
+  'channel-opened': 'Channel opened',
+  'channel-settled': 'Channel settled',
+  'compound-policy-created': 'Compound policy created',
+  'fee-rebalance-swap': 'Fees rebalanced',
+  'fee-user-token-set': 'Fee user token set',
+  'fee-validator-token-set': 'Fee validator token set',
+  'fees-distributed': 'Fees distributed',
+  initialized: 'Initialized',
+  'key-authorization-witness': 'Key authorization witnessed',
+  'key-authorization-witness-burned': 'Key authorization witness burned',
+  'master-registered': 'Master registered',
+  mint: 'Token minted',
+  'network-identity-rotation-epoch-set': 'Network identity rotation epoch set',
+  'nonce-incremented': 'Nonce incremented',
+  'order-cancelled': 'Order cancelled',
+  'order-filled': 'Order filled',
+  'order-flipped': 'Order flipped',
+  'order-placed': 'Order placed',
+  'ownership-transferred': 'Ownership transferred',
+  'pair-created': 'Trading pair created',
+  'policy-admin-set': 'Policy admin set',
+  'policy-created': 'Policy created',
+  'reward-distributed': 'Reward distributed',
+  'reward-recipient-set': 'Reward recipient set',
+  'role-admin-set': 'Role admin set',
+  'role-membership-set': 'Role membership set',
+  'session-closed': 'Session closed',
+  'spending-limit-updated': 'Spending limit updated',
+  swap: 'Tokens swapped',
+  'token-created': 'Token created',
+  'token-logo-set': 'Token logo set',
+  'token-next-quote-token-set': 'Token next quote token set',
+  'token-pause-set': 'Token pause set',
+  'token-quote-token-set': 'Token quote token set',
+  'token-supply-cap-set': 'Token supply cap set',
+  'token-transfer-policy-set': 'Token transfer policy set',
+  transfer: 'Token transferred',
+  unknown: 'Unknown',
+  'validator-added': 'Validator added',
+  'validator-deactivated': 'Validator deactivated',
+  'validator-fee-recipient-set': 'Validator fee recipient set',
+  'validator-ip-set': 'Validator IP set',
+  'validator-migrated': 'Validator migrated',
+  'validator-migration-skipped': 'Validator migration skipped',
+  'validator-ownership-transferred': 'Validator ownership transferred',
+  'validator-rotated': 'Validator rotated',
+  'whitelist-updated': 'Whitelist updated',
+}
+
+/** Stamps the display {@link Item.title} onto a classified item from {@link titleByType}. */
+function withTitle<item extends RawItem>(item: item): item & { title: string } {
+  return { ...item, title: titleByType[item.type] }
+}
+
+/**
+ * Human-readable label for each `viem/tempo` ABI event name, used to title the
+ * entries of an item's raw `events` capture. Keyed by event name (not activity
+ * type), so co-located logs read naturally even when they are not the headline.
+ */
+const titleByEventName: Record<string, string> = {
+  AccessKeySpend: 'Access key spent',
+  Approval: 'Allowance approved',
+  BlacklistUpdated: 'Blacklist updated',
+  Burn: 'Token burned',
+  BurnBlocked: 'Burn blocked',
+  ChannelClosed: 'Channel closed',
+  ChannelOpened: 'Channel opened',
+  CloseRequestCancelled: 'Channel close cancelled',
+  CloseRequested: 'Channel close requested',
+  CompoundPolicyCreated: 'Compound policy created',
+  FeeRecipientUpdated: 'Validator fee recipient set',
+  FeesDistributed: 'Fees distributed',
+  Initialized: 'Initialized',
+  IpAddressesUpdated: 'Validator IP set',
+  KeyAuthorizationWitness: 'Key authorization witnessed',
+  KeyAuthorizationWitnessBurned: 'Key authorization witness burned',
+  KeyAuthorized: 'Access key created',
+  KeyRevoked: 'Access key revoked',
+  LogoURIUpdated: 'Token logo set',
+  MasterRegistered: 'Master registered',
+  Mint: 'Token minted',
+  NetworkIdentityRotationEpochSet: 'Network identity rotation epoch set',
+  NextQuoteTokenSet: 'Token next quote token set',
+  NonceIncremented: 'Nonce incremented',
+  OrderCancelled: 'Order cancelled',
+  OrderFilled: 'Order filled',
+  OrderFlipped: 'Order flipped',
+  OrderPlaced: 'Order placed',
+  OwnershipTransferred: 'Ownership transferred',
+  PairCreated: 'Trading pair created',
+  PauseStateUpdate: 'Token pause set',
+  PolicyAdminUpdated: 'Policy admin set',
+  PolicyCreated: 'Policy created',
+  QuoteTokenUpdate: 'Token quote token set',
+  RebalanceSwap: 'Fees rebalanced',
+  RewardDistributed: 'Reward distributed',
+  RewardRecipientSet: 'Reward recipient set',
+  RoleAdminUpdated: 'Role admin set',
+  RoleMembershipUpdated: 'Role membership set',
+  Settled: 'Channel settled',
+  SkippedValidatorMigration: 'Validator migration skipped',
+  SpendingLimitUpdated: 'Spending limit updated',
+  SupplyCapUpdate: 'Token supply cap set',
+  TokenCreated: 'Token created',
+  TopUp: 'Channel funded',
+  Transfer: 'Token transferred',
+  TransferPolicyUpdate: 'Token transfer policy set',
+  TransferWithMemo: 'Token transferred',
+  UserTokenSet: 'Fee user token set',
+  ValidatorAdded: 'Validator added',
+  ValidatorDeactivated: 'Validator deactivated',
+  ValidatorMigrated: 'Validator migrated',
+  ValidatorOwnershipTransferred: 'Validator ownership transferred',
+  ValidatorRotated: 'Validator rotated',
+  ValidatorTokenSet: 'Fee validator token set',
+  WhitelistUpdated: 'Whitelist updated',
+}
+
+// keccak256("CloseRequested(bytes32,address,address,uint256)") — emitted by a
+// payment channel when settlement is requested; matched on the raw selector
+// because it is not part of the merged `viem/tempo` ABI.
+const closeRequestedSelector = '0xf5a36fc00a96cbb9cf1f8f59299165e1d8ffffe94396d82904b4da524d16bbce'
+
+// keccak256("AccessKeySpend(address,address,address,uint256,uint256)") — emitted
+// by the accountKeychain whenever a tx is signed by an access key. topic2 is the
+// access-key publicKey, i.e. the real signer.
+const accessKeySpendSelector = '0xe0815e3aaadddf4dd75bde97fc060f0c38afe18e87a169be86a3f5c28247f192'
+
+/** TIP-20 / ERC-20 `Transfer` event signature for the decoded CTE. */
+const transferSignature = 'event Transfer(address indexed from, address indexed to, uint256 value)'
+
+// TIP-20 payment-channel reserve precompile. Not exported by `viem/tempo`
+// `Addresses`, so the known address is pinned here: channel events
+// (`ChannelOpened`/`Settled`/`TopUp`/`ChannelClosed`) are emitted here, and
+// their paired TIP-20 `Transfer` legs use it as the funding counterparty, which
+// is how `channel-funded`/`channel-settled`/`channel-closed` recover the token.
+const tip20ChannelReserve = '0x4d50500000000000000000000000000000000000' as Address.Address
+
+/** Number of grouped entries to target before stopping the page-fetch loop. */
+const minGroupEntries = 5
+
+/** Largest number of items folded into a single access-key group. */
+const maxGroupSize = 50
+
+/** Token-bearing keys on an item's `data` payload, walked for enrichment. */
+const tokenKeys = ['destinationToken', 'refund', 'sourceToken'] as const
+
+/** The base fields ({@link schema.base}) every activity item carries. */
+type Base = {
+  id: string
+  logIndex: number
+  perspective: 'incoming' | 'outgoing'
+  timestamp: string
+  transactionHash: Hex.Hex
+}
+
+/** Builds common public activity fields from the normalized transaction hash and representative log. */
+function baseFor(options: {
+  logIndex: number
+  perspective: 'incoming' | 'outgoing'
+  timestamp: string
+  transactionHash: Hex.Hex
+}): Base {
+  return {
+    perspective: options.perspective,
+    id: `${options.transactionHash}-${options.logIndex}`,
+    logIndex: options.logIndex,
+    timestamp: options.timestamp,
+    transactionHash: options.transactionHash,
+  }
+}
+
+/**
+ * A normalized provider row. Mirrors the TIDX `receipts ⋈ logs` join
+ * (`source: 'q1'`, full log columns) and the decoded `Transfer` projection
+ * (`source: 'q2'`, transfer columns), so the classification pipeline does not
+ * care which query produced the row.
+ */
+export type Row = {
+  blockNum: number
+  blockTimestamp: number
+  data: string | null
+  feePayer: Address.Address | null
+  logAddress: Address.Address
+  logIdx: number
+  selector: string | null
+  source: 'q1' | 'q2'
+  topic1: string | null
+  topic2: string | null
+  topic3: string | null
+  transferAmount?: bigint
+  transferFrom?: Address.Address
+  transferTo?: Address.Address
+  transferToken?: Address.Address
+  txHash: Hex.Hex
+  txIdx: number
+  txSender: Address.Address | null
+}
+
+/** A swappable activity data source. */
+export type Provider = {
+  /** Encodes the opaque cursor that resumes strictly after `group`. */
+  cursorForGroup(group: { blockNum: number; txIdx: number }): string
+  /** Fetches a window of merged rows in `(blockNum desc, txIdx desc)` order. */
+  fetchRows(options: {
+    address: Address.Address
+    cursor?: string | undefined
+    limit: number
+  }): Promise<{ rows: Row[] }>
+}
+
+/** Internal group of rows that share a transaction hash. */
+type TxGroup = {
+  blockNum: number
+  blockTimestamp: number
+  feePayer: Address.Address | null
+  rows: Row[]
+  txHash: Hex.Hex
+  txIdx: number
+  txSender: Address.Address | null
+}
+
+/**
+ * Creates address-scoped activity handlers, mounted under the `/addresses`
+ * composer. Exposes `GET /:address/activities`.
+ *
+ * Runs the full activity classification pipeline: three TIDX sub-queries
+ * (outbound `receipts ⋈ logs`, inbound transfers, outbound transfers) merged
+ * and decoded into typed items (`transfer`/`mint`/`burn`/`swap`/
+ * `approval`/`session-closed`/`access-key-created`/`access-key-revoked`/
+ * `token-created`/`burn-blocked`/`channel-opened`/`channel-funded`/
+ * `channel-settled`/`channel-closed`/`channel-close-cancelled`/
+ * `order-placed`/`order-cancelled`/`order-filled`/`order-flipped`/
+ * `pair-created`/`fees-distributed`/`fee-rebalance-swap`/`reward-distributed`/
+ * `reward-recipient-set`/`spending-limit-updated`/ token, fee, policy, registry,
+ * access-key-witness and validator admin events (e.g. `token-pause-set`,
+ * `policy-created`, `validator-added`)/`unknown`), then folds
+ * consecutive access-key-signed items into `group` entries. Pagination uses the
+ * same `(block_num, tx_idx)` keyset cursor the pipeline emits.
+ */
+export function addresses() {
+  return new Hono<App.Environment>().get(
+    '/: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.',
+    }),
+    OpenApi.validate('query', schema.getAddressActivities.Query, {
+      code: 'query_invalid',
+      message: 'Check the query parameters and try again.',
+    }),
+    OpenApi.describeRoute({
+      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.' },
+        success: {
+          description: 'A page of address activity entries.',
+          schema: schema.getAddressActivities.Response,
+        },
+      }),
+      summary: 'List address activities',
+      tags: ['Activities'],
+    }),
+    Cache.response<App.Environment>({
+      cacheControl: Cache.policies.feed,
+      name: 'tempo-api:addresses:v1',
+      key: (c) => Cache.urlKey(c, schema.getAddressActivities.Query),
+    }),
+    async (c) => {
+      if (Auth.narrowAccess) return Auth.paidAccessError(c)
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'address_invalid',
+          message: 'Check the account address and try again.',
+        })
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'query_invalid',
+          message: 'Check the query parameters and try again.',
+        })
+
+      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)
+
+      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,
+                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),
+            },
+          ),
+        )
+
+        // 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 })
+
+        // 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,
+            nextCursor,
+          }),
+          200,
+        )
+      } catch (cause) {
+        return Response.upstream(c, cause)
+      }
+    },
+  )
+}
+
+/**
+ * Creates transaction-scoped activity handlers, mounted under the
+ * `/transactions` composer. Exposes `GET /:transactionHash/activities`.
+ *
+ * Runs the same `groupByTx` → `classifyGroup` pipeline the address feed uses
+ * over a single transaction's logs, anchored on the transaction sender as the
+ * viewer (a transaction-scoped feed has no subject account). Returns the
+ * classified item(s) — usually one headline activity — with the full per-tx
+ * event set available via `logs=true`.
+ */
+export function transactions() {
+  return new Hono<App.Environment>().get(
+    '/: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.',
+    }),
+    OpenApi.validate('query', schema.getTransactionActivities.Query, {
+      code: 'query_invalid',
+      message: 'Check the query parameters and try again.',
+    }),
+    OpenApi.describeRoute({
+      description:
+        'Get a human-readable list of what happened on one transaction onchain, including payments, swaps, approvals, and more.',
+      operationId: 'getTransactionActivities',
+      responses: OpenApi.responses({
+        errors: {
+          404: {
+            description: 'No mined transaction was found for that hash.',
+            codes: ['transaction_not_found'],
+          },
+          502: 'Tempo could not read activity data from the upstream indexer.',
+        },
+        success: {
+          description: 'The classified activity for the transaction.',
+          schema: schema.getTransactionActivities.Response,
+        },
+      }),
+      summary: 'List transaction activities',
+      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.
+      cacheControl: Cache.policies.noStore,
+      name: 'tempo-api:transactions:v1',
+      key: (c) => Cache.urlKey(c, schema.getTransactionActivities.Query),
+    }),
+    async (c) => {
+      if (Auth.narrowAccess) return Auth.paidAccessError(c)
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'transaction_invalid',
+          message: 'Check the transaction hash and try again.',
+        })
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'query_invalid',
+          message: 'Check the query parameters and try again.',
+        })
+
+      const { transactionHash } = c.req.valid('param')
+      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({
+                chainId,
+                logs: query.logs,
+                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),
+            },
+          ),
+        )
+
+        if (items === 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,
+        )
+      } catch (cause) {
+        return Response.upstream(c, cause)
+      }
+    },
+  )
+}
+
+/**
+ * Classifies the activity for a single transaction. Fetches the transaction's
+ * receipt (for its block position, sender, and fee payer) and its logs, then
+ * runs the same `groupByTx` → `classifyGroup` pipeline the address feed uses,
+ * anchored on the transaction sender as the viewer. Returns `null` when no
+ * receipt exists for the hash (an unknown or not-yet-mined transaction), or an
+ * empty list for a mined transaction that emitted no classifiable logs.
+ *
+ * Items carry stub tokens; the caller enriches them via {@link enrichTokens}.
+ */
+export async function getTransactionActivities(
+  options: getTransactionActivities.Options,
+): Promise<Item[] | null> {
+  const { chainId, logs = false, tidx: tidxClient } = options
+  const hash = options.transactionHash.toLowerCase()
+
+  // The `receipts` table is indexed by `tx_hash`, so this point lookup needs no
+  // block bound; it also yields the block number the `logs` lookup requires.
+  // Raw-table query (no signature-decoded CTE), so the inline SQL is cast to
+  // `string`.
+  const receiptResult = await tidxClient.fetch({
+    chainId,
+    query:
+      `SELECT block_num, tx_idx, "from", fee_payer FROM receipts WHERE tx_hash = '${hash}' LIMIT 1` as string,
+  })
+  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'])
+
+  // `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).
+  const logsResult = await tidxClient.fetch({
+    chainId,
+    query:
+      `SELECT tx_hash, block_num, block_timestamp, tx_idx, log_idx, address, selector, topic1, topic2, topic3, data FROM logs WHERE block_num = ${blockNum} AND tx_hash = '${hash}' ORDER BY log_idx ASC` as string,
+  })
+
+  const rows: Row[] = logsResult.rows.map((r) => ({
+    blockNum: Number(Value.toNumber(r['block_num'])),
+    blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
+    data: Value.toText(r['data']) ?? null,
+    feePayer,
+    logAddress: lower(r['address']),
+    logIdx: Number(Value.toNumber(r['log_idx'])),
+    selector: Value.toText(r['selector']) ?? null,
+    source: 'q1' as const,
+    topic1: Value.toText(r['topic1']) ?? null,
+    topic2: Value.toText(r['topic2']) ?? null,
+    topic3: Value.toText(r['topic3']) ?? null,
+    txHash: lowerHash(r['tx_hash']),
+    txIdx: Number(Value.toNumber(r['tx_idx'])),
+    txSender,
+  }))
+
+  // A mined transaction with no logs (e.g. a plain value transfer) has no
+  // classifiable activity; return an empty list rather than a fabricated item.
+  if (rows.length === 0) return []
+
+  // 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(() => ({}))
+
+  // Anchor the viewer on the transaction sender: the sender initiated every
+  // activity in the transaction, so `perspective` is `outgoing` and `signer`
+  // resolves to `self`. Fall back to the zero address when the sender is absent.
+  const viewer = (txSender ?? zeroAddress) as Address.Address
+  const group = groupByTx(rows)[0]!
+  return classifyGroup(group, viewer, fingerprintMap, logs).map(withTitle)
+}
+
+export declare namespace getTransactionActivities {
+  /** Options for {@link getTransactionActivities}. */
+  type Options = {
+    /** Source chain id. */
+    chainId: number
+    /** Attach each item's full transaction `events` capture (decoded + raw logs). */
+    logs?: boolean | undefined
+    /** Cache store for the MPP fingerprint-directory lookup. */
+    store: Store.Store
+    /** TIDX query client. */
+    tidx: Tidx.Client
+    /** Transaction hash to classify. */
+    transactionHash: string
+  }
+}
+
+/**
+ * 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.
+ */
+export async function list(provider: Provider, options: list.Options): Promise<list.ReturnType> {
+  const { address, cursor, group = false, limit = 20, logs = false } = options
+  const viewer = address.toLowerCase() as Address.Address
+
+  // 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(() => ({}))
+
+  let currentCursor: string | undefined = cursor
+  const allItems: Item[] = []
+  let hasMore = false
+  let lastGroup: TxGroup | undefined
+
+  // Fetch pages until the target entry count is reached (or no more rows
+  // exist), up to three attempts. When folding is requested the target is
+  // measured against grouped entries (folding can collapse a page to very few),
+  // otherwise against the raw item count.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const { rows } = await provider.fetchRows({ address: viewer, cursor: currentCursor, limit })
+    const grouped = groupByTx(rows)
+
+    const txGroups = grouped.slice(0, limit + 1)
+    hasMore = txGroups.length > limit
+    const page = txGroups.slice(0, limit)
+
+    if (page.length === 0) break
+
+    allItems.push(
+      ...page.flatMap((txGroup) =>
+        classifyGroup(txGroup, viewer, fingerprintMap, logs).map(withTitle),
+      ),
+    )
+    lastGroup = page[page.length - 1]
+
+    const enough = group
+      ? groupByAccessKey(allItems).length >= minGroupEntries
+      : allItems.length >= limit
+    if (enough || !hasMore) break
+
+    if (lastGroup) currentCursor = provider.cursorForGroup(lastGroup)
+  }
+
+  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}.
+  return { items: allItems, nextCursor }
+}
+
+export declare namespace list {
+  /** Options for {@link list}. */
+  type Options = {
+    /** Subject account address. */
+    address: Address.Address
+    /** Opaque cursor from a previous page; omit for the head page. */
+    cursor?: string | undefined
+    /** Whether the caller will fold items into access-key groups (tunes the page-fill target). */
+    group?: boolean | undefined
+    /** Attach each item's full transaction `events` capture (decoded + raw logs). */
+    logs?: boolean | undefined
+    /** Target page size (entries after grouping). */
+    limit?: number | undefined
+    /** Cache store for the MPP fingerprint-directory lookup. */
+    store: Store.Store
+  }
+  /** Result of {@link list}. */
+  type ReturnType = {
+    items: Item[]
+    nextCursor: string | null
+  }
+}
+
+/**
+ * Creates a TIDX-backed {@link Provider} that runs three sub-queries in
+ * parallel and merges them:
+ * - Q1 (outbound): `receipts ⋈ logs` for txs where the address is `from` or
+ *   `fee_payer`, yielding full log rows.
+ * - Q2 (inbound): decoded `Transfer` events to the address.
+ * - Q3 (outbound transfers): decoded `Transfer` events from the address
+ *   (catches access-key-signed sends where `tx.from` differs from the address).
+ */
+export function tidx(deps: tidx.Deps): Provider {
+  const { chainId, tidx: tidxClient } = deps
+
+  function parseCursor(cursor: string): { blockNum: number; txIdx: number } | undefined {
+    // Opaque `[blockNum, txIdx]` keyset cursor, the same encoding every other
+    // list endpoint uses; a malformed/forged cursor decodes to `undefined` and
+    // falls back to the head page.
+    const decoded = Cursor.decode(cursor, ['int', 'int'])
+    if (!decoded) return undefined
+    return { blockNum: decoded[0] as number, txIdx: decoded[1] as number }
+  }
+
+  /**
+   * Q1: every log of each transaction the address sent or paid the fee for,
+   * via a single `receipts ⋈ logs` join filtered on `from OR fee_payer`.
+   *
+   * The cursor uses a two-predicate keyset (`block_num <= N` AND `(block_num <
+   * N OR tx_idx < M)`) rather than a plain `block_num < N`: the `<= N` upper
+   * bound lets the ClickHouse planner seek to the cursor block on the
+   * `(block_num, tx_idx)` primary key instead of scanning from the tip, which
+   * is what avoids planner 422s on busy addresses. Over-fetch `limit * 4`
+   * (never `OFFSET`) because one tx fans out into many log rows that
+   * `groupByTx` collapses back into a single group.
+   */
+  async function queryOutbound(options: {
+    address: Address.Address
+    cursor: { blockNum: number; txIdx: number } | undefined
+    limit: number
+  }): Promise<Row[]> {
+    const { address, cursor, limit } = options
+    const keyset = cursor
+      ? `AND receipts.block_num <= ${cursor.blockNum} AND (receipts.block_num < ${cursor.blockNum} OR receipts.tx_idx < ${cursor.txIdx})`
+      : ''
+    // Raw-table join (no signature-decoded CTE), so inline SQL is cast to `string`.
+    const result = await tidxClient.fetch({
+      chainId,
+      query: `
+        SELECT
+          receipts.tx_hash AS tx_hash,
+          receipts.block_num AS block_num,
+          receipts.block_timestamp AS block_timestamp,
+          receipts.tx_idx AS tx_idx,
+          receipts."from" AS tx_sender,
+          receipts.fee_payer AS fee_payer,
+          logs.address AS log_address,
+          logs.selector AS selector,
+          logs.topic1 AS topic1,
+          logs.topic2 AS topic2,
+          logs.topic3 AS topic3,
+          logs.data AS data,
+          logs.log_idx AS log_idx
+        FROM receipts
+        INNER JOIN logs ON logs.tx_hash = receipts.tx_hash
+        WHERE (receipts."from" = '${address}' OR receipts.fee_payer = '${address}') ${keyset}
+        ORDER BY receipts.block_num DESC, receipts.tx_idx DESC
+        LIMIT ${limit * 4}
+      ` as string,
+    })
+
+    return result.rows.map((r) => ({
+      blockNum: Number(Value.toNumber(r['block_num'])),
+      blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
+      data: Value.toText(r['data']) ?? null,
+      feePayer: lowerOrNull(r['fee_payer']),
+      logAddress: lower(r['log_address']),
+      logIdx: Number(Value.toNumber(r['log_idx'])),
+      selector: Value.toText(r['selector']) ?? null,
+      source: 'q1' as const,
+      topic1: Value.toText(r['topic1']) ?? null,
+      topic2: Value.toText(r['topic2']) ?? null,
+      topic3: Value.toText(r['topic3']) ?? null,
+      txHash: lowerHash(r['tx_hash']),
+      txIdx: Number(Value.toNumber(r['tx_idx'])),
+      txSender: lowerOrNull(r['tx_sender']),
+    }))
+  }
+
+  /** Q2/Q3: decoded `Transfer` events on one side of the address. */
+  async function queryTransfers(options: {
+    address: Address.Address
+    cursor: { blockNum: number; txIdx: number } | undefined
+    limit: number
+    side: 'inbound' | 'outbound'
+  }): Promise<Row[]> {
+    const { address, cursor, limit, side } = options
+    const where =
+      side === 'inbound'
+        ? `"to" = '${address}' AND "from" != '${address}'`
+        : `"from" = '${address}' AND "to" != '${address}'`
+    const keyset = cursor ? `AND block_num < ${cursor.blockNum}` : ''
+    const result = await tidxClient.fetch({
+      chainId,
+      query: `
+        SELECT "from", "to", address, value, tx_hash, block_num, block_timestamp, log_idx, tx_idx
+        FROM Transfer
+        WHERE ${where} ${keyset}
+        ORDER BY block_num DESC, tx_idx DESC
+        LIMIT ${limit * 4}
+      `,
+      signatures: [transferSignature],
+    })
+    return result.rows.map((r) => ({
+      blockNum: Number(Value.toNumber(r['block_num'])),
+      blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
+      data: null,
+      feePayer: null,
+      logAddress: lower(r['address']),
+      logIdx: Number(Value.toNumber(r['log_idx'])),
+      selector: null,
+      source: 'q2' as const,
+      topic1: null,
+      topic2: null,
+      topic3: null,
+      transferAmount: BigInt(Value.toIntegerString(r['value']) ?? '0'),
+      transferFrom: lower(r['from']),
+      transferTo: lower(r['to']),
+      transferToken: lower(r['address']),
+      txHash: lowerHash(r['tx_hash']),
+      txIdx: Number(Value.toNumber(r['tx_idx'])),
+      txSender: null,
+    }))
+  }
+
+  return {
+    cursorForGroup(group) {
+      return Cursor.encode([group.blockNum, group.txIdx])
+    },
+    async fetchRows({ address, cursor, limit }) {
+      const parsed = cursor ? parseCursor(cursor) : undefined
+      const [q1, q2, q3] = await Promise.all([
+        queryOutbound({ address, cursor: parsed, limit }),
+        queryTransfers({ address, cursor: parsed, limit, side: 'inbound' }),
+        queryTransfers({ address, cursor: parsed, limit, side: 'outbound' }),
+      ])
+      return { rows: mergeAndSort(q1, q2, q3) }
+    },
+  }
+}
+
+export declare namespace tidx {
+  /** Dependencies for {@link tidx}. */
+  type Deps = {
+    /** Source chain id. */
+    chainId: number
+    /** TIDX query client. */
+    tidx: Tidx.Client
+  }
+}
+
+/**
+ * Merges three sub-query results into one `(blockNum desc, txIdx desc)` stream.
+ * Q2/Q3 rows whose hash already appears in Q1 are dropped (Q1 rows are richer),
+ * and Q3 is also deduped against Q2.
+ */
+export function mergeAndSort(q1: readonly Row[], q2: readonly Row[], q3: readonly Row[]): Row[] {
+  const q1Hashes = new Set(q1.map((r) => r.txHash))
+  const filteredQ2 = q2.filter((r) => !q1Hashes.has(r.txHash))
+  const filteredQ3 = q3.filter((r) => !q1Hashes.has(r.txHash))
+  const q2Hashes = new Set(filteredQ2.map((r) => r.txHash))
+  const dedupedQ3 = filteredQ3.filter((r) => !q2Hashes.has(r.txHash))
+  return [...q1, ...filteredQ2, ...dedupedQ3].sort((a, b) => {
+    if (a.blockNum !== b.blockNum) return b.blockNum - a.blockNum
+    return b.txIdx - a.txIdx
+  })
+}
+
+/** Groups rows by transaction hash, preserving sort order. */
+function groupByTx(rows: Row[]): TxGroup[] {
+  const map = new Map<string, TxGroup>()
+  const order: string[] = []
+
+  for (const row of rows) {
+    const key = row.txHash
+    let group = map.get(key)
+    if (!group) {
+      group = {
+        blockNum: row.blockNum,
+        blockTimestamp: row.blockTimestamp,
+        feePayer: row.feePayer,
+        rows: [],
+        txHash: row.txHash,
+        txIdx: row.txIdx,
+        txSender: row.txSender,
+      }
+      map.set(key, group)
+      order.push(key)
+    }
+    // Inherit tx sender / fee payer from richer Q1 rows when present.
+    if (row.txSender && !group.txSender) group.txSender = row.txSender
+    if (row.feePayer && !group.feePayer) group.feePayer = row.feePayer
+    group.rows.push(row)
+  }
+
+  return order.map((key) => map.get(key)!)
+}
+
+/**
+ * Classifies a transaction group into one or more activity items. Q1 groups go
+ * through full log decoding; Q2-only groups (transfers without a joined receipt)
+ * are classified directly from the transfer columns.
+ */
+function classifyGroup(
+  group: TxGroup,
+  viewer: Address.Address,
+  fingerprintMap: Record<string, string>,
+  includeLogs = false,
+): RawItem[] {
+  const { blockNum, blockTimestamp, feePayer, txHash, txSender } = group
+  // `blockTimestamp` is epoch seconds; the public feed uses ISO 8601 like every
+  // other resource's `timestamp`.
+  const timestamp = new Date(Number(blockTimestamp) * 1000).toISOString()
+  // `outgoing` when the viewer initiated the transaction (sent it or paid the
+  // fee); `incoming` when it merely happened to them (someone else initiated it).
+  const perspective: 'incoming' | 'outgoing' =
+    (txSender && Address.isEqual(txSender, viewer)) ||
+    (feePayer && Address.isEqual(feePayer, viewer))
+      ? 'outgoing'
+      : 'incoming'
+  const itemBase = (logIndex: number) =>
+    baseFor({ logIndex, perspective, timestamp, transactionHash: txHash })
+  const signer: 'self' | Address.Address =
+    txSender && Address.isEqual(txSender, viewer) ? 'self' : (txSender ?? 'self')
+
+  const q1Rows = group.rows.filter((r) => r.source === 'q1')
+  const q2Rows = group.rows.filter((r) => r.source === 'q2')
+
+  if (q1Rows.length > 0)
+    return classifyFromLogs(q1Rows, {
+      blockNum,
+      fingerprintMap,
+      includeLogs,
+      itemBase,
+      signer,
+      viewer,
+    })
+
+  // Q2-only — a transfer row without a joined receipt. Classify by comparing
+  // `from`/`to` against the viewer (zero-address sides are mints/burns).
+  if (q2Rows.length > 0) {
+    const r = q2Rows[0]!
+    const base = itemBase(r.logIdx)
+    const from = r.transferFrom!
+    const to = r.transferTo!
+    const sourceToken = token(r.transferAmount, r.transferToken!)
+    if (Address.isEqual(from, zeroAddress as Address.Address))
+      return [{ ...base, data: { recipient: viewer, sourceToken }, type: 'mint' }]
+    if (Address.isEqual(to, zeroAddress as Address.Address))
+      return [{ ...base, data: { sender: from, signer, sourceToken }, type: 'burn' }]
+    // Q2-only rows carry no memo, so MPP service attribution is unavailable
+    // here; `attribution` is resolved only on the log-bearing (Q1) path.
+    if (Address.isEqual(from, viewer))
+      return [
+        transfer(base, blockNum, {
+          direction: 'out',
+          recipient: to,
+          sender: viewer,
+          signer,
+          sourceToken,
+        }),
+      ]
+    return [
+      transfer(base, blockNum, { direction: 'in', recipient: viewer, sender: from, sourceToken }),
+    ]
+  }
+
+  // Fallback — should not happen (a group with neither q1 nor q2 rows).
+  return [
+    unknown(itemBase(Math.min(...group.rows.map((r) => r.logIdx))), {
+      events: buildTxEvents(group.rows, []),
+      signer,
+    }),
+  ]
+}
+
+/** Classifies a Q1 (log-bearing) group via `parseEventLogs`. */
+function classifyFromLogs(
+  rows: Row[],
+  ctx: {
+    blockNum: number
+    fingerprintMap: Record<string, string>
+    includeLogs: boolean
+    itemBase: (logIndex: number) => Base
+    signer: 'self' | Address.Address
+    viewer: Address.Address
+  },
+): RawItem[] {
+  const items = classifyFromLogsCore(rows, ctx)
+  // When the caller requested raw logs, attach the full per-transaction log set
+  // (decoded when possible) to every classified item so no co-located log is
+  // hidden behind the headline. `unknown` items already carry it.
+  if (!ctx.includeLogs) return items
+  const events = buildTxEvents(rows, decodeRows(rows))
+  return items.map((item) => (item.type === 'unknown' ? item : { ...item, events }))
+}
+
+/** Classifies a Q1 (log-bearing) group via `parseEventLogs`, picking one headline item. */
+function classifyFromLogsCore(
+  rows: Row[],
+  ctx: {
+    blockNum: number
+    fingerprintMap: Record<string, string>
+    itemBase: (logIndex: number) => Base
+    signer: 'self' | Address.Address
+    viewer: Address.Address
+  },
+): RawItem[] {
+  const { blockNum, fingerprintMap, itemBase, viewer } = ctx
+
+  // An access-key-signed tx emits AccessKeySpend at the accountKeychain; topic2
+  // is the access-key publicKey. Use it as the signer so successive access-key
+  // actions group together.
+  const accessKeySpendRow = rows.find(
+    (r) =>
+      r.selector === accessKeySpendSelector &&
+      Address.isEqual(r.logAddress, Addresses.accountKeychain),
+  )
+  const accessKeySigner = accessKeySpendRow?.topic2
+    ? (`0x${accessKeySpendRow.topic2.slice(-40)}`.toLowerCase() as Address.Address)
+    : null
+  const signer: 'self' | Address.Address =
+    accessKeySigner && !Address.isEqual(accessKeySigner, viewer) ? accessKeySigner : ctx.signer
+
+  const events = decodeRows(rows)
+
+  const minLogIndex = Math.min(...rows.map((r) => r.logIdx))
+
+  // Payment-channel settlement: a CloseRequested topic plus an optional refund
+  // transfer back to the viewer.
+  const hasCloseRequested = rows.some((r) => r.selector === closeRequestedSelector)
+  if (hasCloseRequested) {
+    const closeRequestedLogIndex =
+      rows.find((r) => r.selector === closeRequestedSelector)?.logIdx ?? minLogIndex
+    const refundTransfer = events.find(
+      (e) =>
+        (e.eventName === 'Transfer' || e.eventName === 'TransferWithMemo') &&
+        'to' in e.args &&
+        Address.isEqual((e.args as { to: Address.Address }).to, viewer),
+    )
+    const refund = refundTransfer
+      ? token(
+          (refundTransfer.args as { amount: bigint }).amount,
+          refundTransfer.address as Address.Address,
+        )
+      : undefined
+    return [
+      {
+        ...itemBase(closeRequestedLogIndex),
+        data: { ...(refund ? { refund } : {}), signer },
+        type: 'session-closed',
+      },
+    ]
+  }
+
+  // Dedup preference: TransferWithMemo beats Transfer; Mint/Burn beat
+  // zero-address Transfer.
+  const preferenceMap = new Map<string, string>()
+  for (const event of events) {
+    if (event.eventName === 'TransferWithMemo' && 'from' in event.args && 'to' in event.args) {
+      const args = event.args as { amount: bigint; from: Address.Address; to: Address.Address }
+      preferenceMap.set(`${args.from}:${args.to}:${args.amount}`, 'TransferWithMemo')
+    }
+    if (event.eventName === 'Mint' && 'amount' in event.args)
+      preferenceMap.set(
+        `mint:${event.address}:${(event.args as { amount: bigint }).amount}`,
+        'Mint',
+      )
+    if (event.eventName === 'Burn' && 'amount' in event.args)
+      preferenceMap.set(
+        `burn:${event.address}:${(event.args as { amount: bigint }).amount}`,
+        'Burn',
+      )
+  }
+
+  const dedupedEvents = events.filter((event) => {
+    if (event.eventName !== 'Transfer') return true
+    const args = event.args as { amount: bigint; from: Address.Address; to: Address.Address }
+    if (preferenceMap.has(`${args.from}:${args.to}:${args.amount}`)) return false
+    if (
+      Address.isEqual(args.from, zeroAddress as Address.Address) &&
+      preferenceMap.has(`mint:${event.address}:${args.amount}`)
+    )
+      return false
+    if (
+      Address.isEqual(args.to, zeroAddress as Address.Address) &&
+      preferenceMap.has(`burn:${event.address}:${args.amount}`)
+    )
+      return false
+    return true
+  })
+
+  const finalEvents = dedupedEvents.filter((event) => {
+    if (event.eventName !== 'TransferWithMemo') return true
+    const args = event.args as { amount: bigint; from: Address.Address; to: Address.Address }
+    if (
+      Address.isEqual(args.from, zeroAddress as Address.Address) &&
+      preferenceMap.has(`mint:${event.address}:${args.amount}`)
+    )
+      return false
+    if (
+      Address.isEqual(args.to, zeroAddress as Address.Address) &&
+      preferenceMap.has(`burn:${event.address}:${args.amount}`)
+    )
+      return false
+    return true
+  })
+
+  const transfers = finalEvents.filter(
+    (e) =>
+      (e.eventName === 'Transfer' || e.eventName === 'TransferWithMemo') &&
+      'to' in e.args &&
+      'from' in e.args &&
+      'amount' in e.args,
+  )
+
+  // Swap: a transfer into the DEX paired with one out of the DEX.
+  const toDex = transfers.find((e) =>
+    Address.isEqual((e.args as { to: Address.Address }).to, Addresses.stablecoinDex),
+  )
+  const fromDex = transfers.find((e) =>
+    Address.isEqual((e.args as { from: Address.Address }).from, Addresses.stablecoinDex),
+  )
+  if (toDex && fromDex) {
+    const swapper = (fromDex.args as { to: Address.Address }).to
+    const destTokenAddress = fromDex.address as Address.Address
+    const sourceToken = token(
+      (toDex.args as { amount: bigint }).amount,
+      toDex.address as Address.Address,
+    )
+
+    // Cross-token transfer: the swapped-out token is forwarded from the swapper
+    // to a different recipient in the same transaction (the account server's
+    // approve+swap+transfer multicall). Fold the swap and its delivery leg into
+    // one `transfer` carrying both the source token spent into the DEX and the
+    // destination token delivered to the recipient. A swap whose output stays
+    // with the swapper (no onward leg) stays a plain `swap` below.
+    const delivery = transfers.find(
+      (e) =>
+        Address.isEqual(e.address, destTokenAddress) &&
+        Address.isEqual((e.args as { from: Address.Address }).from, swapper) &&
+        !Address.isEqual((e.args as { to: Address.Address }).to, Addresses.stablecoinDex) &&
+        !Address.isEqual((e.args as { to: Address.Address }).to, swapper),
+    )
+    if (delivery) {
+      const args = delivery.args as {
+        amount: bigint
+        from: Address.Address
+        memo?: Hex.Hex | undefined
+        to: Address.Address
+      }
+      const rawMemo = delivery.eventName === 'TransferWithMemo' ? args.memo : undefined
+      const memo = rawMemo ? Transfers.memoToString(rawMemo) : undefined
+      const attribution = Mpp.resolve({ fingerprintMap, memo: rawMemo })
+      return [
+        transfer(itemBase(logIndexOfEvent(delivery)), blockNum, {
+          attribution,
+          destinationToken: token(args.amount, delivery.address as Address.Address),
+          direction: Address.isEqual(args.to, viewer) ? 'in' : 'out',
+          memo,
+          recipient: args.to.toLowerCase() as Address.Address,
+          sender: swapper.toLowerCase() as Address.Address,
+          signer,
+          sourceToken,
+        }),
+      ]
+    }
+
+    return [
+      {
+        ...itemBase(Math.min(logIndexOfEvent(toDex), logIndexOfEvent(fromDex))),
+        data: {
+          destinationToken: token((fromDex.args as { amount: bigint }).amount, destTokenAddress),
+          signer,
+          sourceToken,
+        },
+        type: 'swap',
+      },
+    ]
+  }
+
+  // Mint: explicit `Mint` event (not the fee manager) or a transfer from zero.
+  const mintEvent = finalEvents.find(
+    (e) =>
+      e.eventName === 'Mint' &&
+      'amount' in e.args &&
+      !Address.isEqual(e.address, Addresses.feeManager),
+  )
+  if (mintEvent) {
+    const args = mintEvent.args as { amount: bigint; to: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(mintEvent)),
+        data: {
+          recipient: args.to.toLowerCase() as Address.Address,
+          sourceToken: token(args.amount, mintEvent.address as Address.Address),
+        },
+        type: 'mint',
+      },
+    ]
+  }
+  const zeroTransferIn = transfers.find((e) =>
+    Address.isEqual((e.args as { from: Address.Address }).from, zeroAddress as Address.Address),
+  )
+  if (zeroTransferIn) {
+    const args = zeroTransferIn.args as { amount: bigint; to: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(zeroTransferIn)),
+        data: {
+          recipient: (args.to as string).toLowerCase() as Address.Address,
+          sourceToken: token(args.amount, zeroTransferIn.address as Address.Address),
+        },
+        type: 'mint',
+      },
+    ]
+  }
+
+  // Burn blocked: a compliance burn of receive-policy-blocked funds. It also
+  // emits a zero-address `Transfer` that would otherwise classify as `burn`, so
+  // detect the distinct `BurnBlocked` event first.
+  const burnBlockedEvent = finalEvents.find((e) => e.eventName === 'BurnBlocked')
+  if (burnBlockedEvent) {
+    const args = burnBlockedEvent.args as { amount: bigint; from: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(burnBlockedEvent)),
+        data: {
+          sender: args.from.toLowerCase() as Address.Address,
+          signer,
+          sourceToken: token(args.amount, burnBlockedEvent.address as Address.Address),
+        },
+        type: 'burn-blocked',
+      },
+    ]
+  }
+
+  // Burn: explicit `Burn` event or a transfer to zero.
+  const burnEvent = finalEvents.find((e) => e.eventName === 'Burn' && 'amount' in e.args)
+  if (burnEvent) {
+    const args = burnEvent.args as { amount: bigint; from: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(burnEvent)),
+        data: {
+          sender: args.from.toLowerCase() as Address.Address,
+          signer,
+          sourceToken: token(args.amount, burnEvent.address as Address.Address),
+        },
+        type: 'burn',
+      },
+    ]
+  }
+  const zeroTransferOut = transfers.find((e) =>
+    Address.isEqual((e.args as { to: Address.Address }).to, zeroAddress as Address.Address),
+  )
+  if (zeroTransferOut) {
+    const args = zeroTransferOut.args as { amount: bigint; from: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(zeroTransferOut)),
+        data: {
+          sender: (args.from as string).toLowerCase() as Address.Address,
+          signer,
+          sourceToken: token(args.amount, zeroTransferOut.address as Address.Address),
+        },
+        type: 'burn',
+      },
+    ]
+  }
+
+  // Approval (excluding zone-outbox spenders).
+  const approvalEvent = finalEvents.find(
+    (e) =>
+      e.eventName === 'Approval' &&
+      !Address.isEqual((e.args as { spender: Address.Address }).spender, Addresses.zoneOutbox),
+  )
+  if (approvalEvent) {
+    const args = approvalEvent.args as { amount: bigint; spender: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(approvalEvent)),
+        data: {
+          signer,
+          sourceToken: token(args.amount, approvalEvent.address as Address.Address),
+          spender: args.spender.toLowerCase() as Address.Address,
+        },
+        type: 'approval',
+      },
+    ]
+  }
+
+  // Precompile-event activities. These run before the generic transfer
+  // fallback because each is emitted alongside a co-located TIP-20 `Transfer`
+  // whose counterparty is the precompile (the DEX, the channel reserve, the fee
+  // manager, the token itself), which would otherwise classify as a plain
+  // transfer. They are grouped by (transaction + precompile counterparty), not
+  // by log adjacency.
+
+  // Payment channel opened: `ChannelOpened` carries the deposit token/amount
+  // directly, so no paired-transfer lookup is needed.
+  const channelOpened = finalEvents.find((e) => e.eventName === 'ChannelOpened')
+  if (channelOpened) {
+    const args = channelOpened.args as {
+      channelId: Hex.Hex
+      deposit: bigint
+      payee: Address.Address
+      payer: Address.Address
+      token: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(channelOpened)),
+        data: {
+          channelId: args.channelId.toLowerCase() as Hex.Hex,
+          payee: args.payee.toLowerCase() as Address.Address,
+          payer: args.payer.toLowerCase() as Address.Address,
+          signer,
+          sourceToken: token(args.deposit, args.token),
+        },
+        type: 'channel-opened',
+      },
+    ]
+  }
+
+  // The channel reserve doesn't put the token on `TopUp`/`Settled`/
+  // `ChannelClosed`, so recover it from the co-located funding/payout transfer.
+  const reserveInflow = transfers.find((e) =>
+    Address.isEqual((e.args as { to: Address.Address }).to, tip20ChannelReserve),
+  )
+  const reserveOutflowTo = (recipient: Address.Address) =>
+    transfers.find(
+      (e) =>
+        Address.isEqual((e.args as { from: Address.Address }).from, tip20ChannelReserve) &&
+        Address.isEqual((e.args as { to: Address.Address }).to, recipient),
+    )
+
+  // Payment channel topped up: `additionalDeposit` from the event, token from
+  // the inbound funding transfer to the reserve.
+  const topUp = finalEvents.find((e) => e.eventName === 'TopUp')
+  if (topUp) {
+    const args = topUp.args as { additionalDeposit: bigint; channelId: Hex.Hex }
+    const tokenAddress = reserveInflow
+      ? (reserveInflow.address as Address.Address)
+      : (zeroAddress as Address.Address)
+    return [
+      {
+        ...itemBase(logIndexOfEvent(topUp)),
+        data: {
+          channelId: args.channelId.toLowerCase() as Hex.Hex,
+          signer,
+          sourceToken: token(args.additionalDeposit, tokenAddress),
+        },
+        type: 'channel-funded',
+      },
+    ]
+  }
+
+  // Payment channel settled: `deltaPaid` from the event, token from the payout
+  // transfer out of the reserve to the payee.
+  const settled = finalEvents.find((e) => e.eventName === 'Settled')
+  if (settled) {
+    const args = settled.args as {
+      channelId: Hex.Hex
+      deltaPaid: bigint
+      payee: Address.Address
+      payer: Address.Address
+    }
+    const payeeLeg = reserveOutflowTo(args.payee.toLowerCase() as Address.Address)
+    const tokenAddress = payeeLeg
+      ? (payeeLeg.address as Address.Address)
+      : (zeroAddress as Address.Address)
+    return [
+      {
+        ...itemBase(logIndexOfEvent(settled)),
+        data: {
+          channelId: args.channelId.toLowerCase() as Hex.Hex,
+          payee: args.payee.toLowerCase() as Address.Address,
+          payer: args.payer.toLowerCase() as Address.Address,
+          signer,
+          sourceToken: token(args.deltaPaid, tokenAddress),
+        },
+        type: 'channel-settled',
+      },
+    ]
+  }
+
+  // Payment channel closed: payout to the payee and refund to the payer arrive
+  // as up to two transfers out of the reserve; attach whichever are present.
+  const channelClosed = finalEvents.find((e) => e.eventName === 'ChannelClosed')
+  if (channelClosed) {
+    const args = channelClosed.args as {
+      channelId: Hex.Hex
+      payee: Address.Address
+      payer: Address.Address
+      refundedToPayer: bigint
+      settledToPayee: bigint
+    }
+    const payeeLeg = reserveOutflowTo(args.payee.toLowerCase() as Address.Address)
+    const payerLeg = reserveOutflowTo(args.payer.toLowerCase() as Address.Address)
+    return [
+      {
+        ...itemBase(logIndexOfEvent(channelClosed)),
+        data: {
+          channelId: args.channelId.toLowerCase() as Hex.Hex,
+          payee: args.payee.toLowerCase() as Address.Address,
+          payer: args.payer.toLowerCase() as Address.Address,
+          ...(payerLeg && args.refundedToPayer > 0n
+            ? { refund: token(args.refundedToPayer, payerLeg.address as Address.Address) }
+            : {}),
+          signer,
+          ...(payeeLeg
+            ? { sourceToken: token(args.settledToPayee, payeeLeg.address as Address.Address) }
+            : {}),
+        },
+        type: 'channel-closed',
+      },
+    ]
+  }
+
+  // Payment channel close cancelled: the payer revoked a pending close request.
+  // When bundled with a top-up the `TopUp` classifier above wins; on its own
+  // this carries no transfer, so the event itself is the signal.
+  const closeCancelled = finalEvents.find((e) => e.eventName === 'CloseRequestCancelled')
+  if (closeCancelled) {
+    const args = closeCancelled.args as {
+      channelId: Hex.Hex
+      payee: Address.Address
+      payer: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(closeCancelled)),
+        data: {
+          channelId: args.channelId.toLowerCase() as Hex.Hex,
+          payee: args.payee.toLowerCase() as Address.Address,
+          payer: args.payer.toLowerCase() as Address.Address,
+          signer,
+        },
+        type: 'channel-close-cancelled',
+      },
+    ]
+  }
+
+  // DEX order placed: `OrderPlaced` carries the escrow token/amount and side.
+  // (Auto-flip re-places are inside swaps, which already returned above.)
+  const orderPlaced = finalEvents.find((e) => e.eventName === 'OrderPlaced')
+  if (orderPlaced) {
+    const args = orderPlaced.args as {
+      amount: bigint
+      isBid: boolean
+      orderId: bigint
+      tick: number
+      token: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(orderPlaced)),
+        data: {
+          orderId: args.orderId.toString(),
+          side: args.isBid ? 'bid' : 'ask',
+          signer,
+          sourceToken: token(args.amount, args.token),
+          tick: Number(args.tick),
+        },
+        type: 'order-placed',
+      },
+    ]
+  }
+
+  // DEX order cancelled: refund is credited to the internal DEX balance, so
+  // there is no co-located transfer — the `OrderCancelled` event is the signal.
+  const orderCancelled = finalEvents.find((e) => e.eventName === 'OrderCancelled')
+  if (orderCancelled) {
+    const args = orderCancelled.args as { orderId: bigint }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(orderCancelled)),
+        data: { orderId: args.orderId.toString(), signer },
+        type: 'order-cancelled',
+      },
+    ]
+  }
+
+  // Fee-AMM rebalance swap: `validatorToken` in, `userToken` out.
+  const rebalanceSwap = finalEvents.find((e) => e.eventName === 'RebalanceSwap')
+  if (rebalanceSwap) {
+    const args = rebalanceSwap.args as {
+      amountIn: bigint
+      amountOut: bigint
+      swapper: Address.Address
+      userToken: Address.Address
+      validatorToken: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(rebalanceSwap)),
+        data: {
+          destinationToken: token(args.amountOut, args.userToken),
+          signer,
+          sourceToken: token(args.amountIn, args.validatorToken),
+          swapper: args.swapper.toLowerCase() as Address.Address,
+        },
+        type: 'fee-rebalance-swap',
+      },
+    ]
+  }
+
+  // Validator fees distributed.
+  const feesDistributed = finalEvents.find((e) => e.eventName === 'FeesDistributed')
+  if (feesDistributed) {
+    const args = feesDistributed.args as {
+      amount: bigint
+      token: Address.Address
+      validator: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(feesDistributed)),
+        data: {
+          signer,
+          sourceToken: token(args.amount, args.token),
+          validator: args.validator.toLowerCase() as Address.Address,
+        },
+        type: 'fees-distributed',
+      },
+    ]
+  }
+
+  // Reward pool funded: the funded token is the emitting token contract itself.
+  const rewardDistributed = finalEvents.find((e) => e.eventName === 'RewardDistributed')
+  if (rewardDistributed) {
+    const args = rewardDistributed.args as { amount: bigint; funder: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(rewardDistributed)),
+        data: {
+          funder: args.funder.toLowerCase() as Address.Address,
+          signer,
+          sourceToken: token(args.amount, rewardDistributed.address as Address.Address),
+        },
+        type: 'reward-distributed',
+      },
+    ]
+  }
+
+  // Reward recipient redirected.
+  const rewardRecipientSet = finalEvents.find((e) => e.eventName === 'RewardRecipientSet')
+  if (rewardRecipientSet) {
+    const args = rewardRecipientSet.args as { holder: Address.Address; recipient: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(rewardRecipientSet)),
+        data: {
+          holder: args.holder.toLowerCase() as Address.Address,
+          recipient: args.recipient.toLowerCase() as Address.Address,
+          signer,
+        },
+        type: 'reward-recipient-set',
+      },
+    ]
+  }
+
+  // Access-key spending limit updated: `newLimit` is carried as the token
+  // amount so it enriches with the token's metadata.
+  const spendingLimitUpdated = finalEvents.find((e) => e.eventName === 'SpendingLimitUpdated')
+  if (spendingLimitUpdated) {
+    const args = spendingLimitUpdated.args as {
+      account: Address.Address
+      newLimit: bigint
+      publicKey: Address.Address
+      token: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(spendingLimitUpdated)),
+        data: {
+          account: args.account.toLowerCase() as Address.Address,
+          publicKey: args.publicKey.toLowerCase() as Address.Address,
+          signer,
+          sourceToken: token(args.newLimit, args.token),
+        },
+        type: 'spending-limit-updated',
+      },
+    ]
+  }
+
+  // Access-key lifecycle events — emitted alongside any co-located transfer.
+  const accessKeyItems: RawItem[] = []
+  for (const event of finalEvents) {
+    if (
+      event.eventName === 'KeyAuthorized' &&
+      Address.isEqual(event.address, Addresses.accountKeychain)
+    ) {
+      const args = event.args as {
+        account: Address.Address
+        expiry: bigint
+        publicKey: Address.Address
+        signatureType: number
+      }
+      accessKeyItems.push({
+        ...itemBase(logIndexOfEvent(event)),
+        data: {
+          account: args.account.toLowerCase() as Address.Address,
+          expiry: Number(args.expiry),
+          publicKey: args.publicKey.toLowerCase() as Address.Address,
+          signatureType: Number(args.signatureType),
+        },
+        type: 'access-key-created',
+      })
+    } else if (
+      event.eventName === 'KeyRevoked' &&
+      Address.isEqual(event.address, Addresses.accountKeychain)
+    ) {
+      const args = event.args as { account: Address.Address; publicKey: Address.Address }
+      accessKeyItems.push({
+        ...itemBase(logIndexOfEvent(event)),
+        data: {
+          account: args.account.toLowerCase() as Address.Address,
+          publicKey: args.publicKey.toLowerCase() as Address.Address,
+        },
+        type: 'access-key-revoked',
+      })
+    }
+  }
+
+  // Token creation.
+  const tokenCreated = finalEvents.find(
+    (e) => e.eventName === 'TokenCreated' && Address.isEqual(e.address, Addresses.tip20Factory),
+  )
+  if (tokenCreated) {
+    const args = tokenCreated.args as {
+      currency: string
+      name: string
+      symbol: string
+      token: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(tokenCreated)),
+        data: {
+          address: args.token.toLowerCase() as Address.Address,
+          currency: args.currency,
+          name: args.name,
+          symbol: args.symbol,
+        },
+        type: 'token-created',
+      },
+      ...accessKeyItems,
+    ]
+  }
+
+  // Governance / admin / DEX-bookkeeping events. Each maps a single decoded
+  // event to a typed item. Checked after token creation (a token-creation tx
+  // also emits `RoleMembershipUpdated`) and before the plain-transfer fallback;
+  // these carry no token movement, so the event itself is the whole signal.
+  const lc = (value: Address.Address) => value.toLowerCase() as Address.Address
+  const hx = (value: Hex.Hex) => value.toLowerCase() as Hex.Hex
+  const findEvent = (name: string) => finalEvents.find((e) => e.eventName === name)
+
+  // DEX bookkeeping (taker swaps and `OrderPlaced` already returned above).
+  const orderFilled = findEvent('OrderFilled')
+  if (orderFilled) {
+    const a = orderFilled.args as {
+      amountFilled: bigint
+      maker: Address.Address
+      orderId: bigint
+      partialFill: boolean
+      taker: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(orderFilled)),
+        data: {
+          amountFilled: a.amountFilled.toString(),
+          maker: lc(a.maker),
+          orderId: a.orderId.toString(),
+          partialFill: a.partialFill,
+          signer,
+          taker: lc(a.taker),
+        },
+        type: 'order-filled',
+      },
+    ]
+  }
+  const orderFlipped = findEvent('OrderFlipped')
+  if (orderFlipped) {
+    const a = orderFlipped.args as {
+      amount: bigint
+      flipTick: number
+      isBid: boolean
+      maker: Address.Address
+      orderId: bigint
+      tick: number
+      token: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(orderFlipped)),
+        data: {
+          flipTick: Number(a.flipTick),
+          maker: lc(a.maker),
+          orderId: a.orderId.toString(),
+          side: a.isBid ? 'bid' : 'ask',
+          signer,
+          sourceToken: token(a.amount, a.token),
+          tick: Number(a.tick),
+        },
+        type: 'order-flipped',
+      },
+    ]
+  }
+  const pairCreated = findEvent('PairCreated')
+  if (pairCreated) {
+    const a = pairCreated.args as { base: Address.Address; key: Hex.Hex; quote: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(pairCreated)),
+        data: { base: lc(a.base), key: hx(a.key), quote: lc(a.quote), signer },
+        type: 'pair-created',
+      },
+    ]
+  }
+
+  // TIP-20 token configuration / admin.
+  const pauseStateUpdate = findEvent('PauseStateUpdate')
+  if (pauseStateUpdate) {
+    const a = pauseStateUpdate.args as { isPaused: boolean; updater: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(pauseStateUpdate)),
+        data: { paused: a.isPaused, signer, updater: lc(a.updater) },
+        type: 'token-pause-set',
+      },
+    ]
+  }
+  const supplyCapUpdate = findEvent('SupplyCapUpdate')
+  if (supplyCapUpdate) {
+    const a = supplyCapUpdate.args as { newSupplyCap: bigint; updater: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(supplyCapUpdate)),
+        data: { signer, supplyCap: a.newSupplyCap.toString(), updater: lc(a.updater) },
+        type: 'token-supply-cap-set',
+      },
+    ]
+  }
+  const transferPolicyUpdate = findEvent('TransferPolicyUpdate')
+  if (transferPolicyUpdate) {
+    const a = transferPolicyUpdate.args as { newPolicyId: bigint; updater: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(transferPolicyUpdate)),
+        data: { policyId: a.newPolicyId.toString(), signer, updater: lc(a.updater) },
+        type: 'token-transfer-policy-set',
+      },
+    ]
+  }
+  const quoteTokenUpdate = findEvent('QuoteTokenUpdate')
+  if (quoteTokenUpdate) {
+    const a = quoteTokenUpdate.args as { newQuoteToken: Address.Address; updater: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(quoteTokenUpdate)),
+        data: { quoteToken: lc(a.newQuoteToken), signer, updater: lc(a.updater) },
+        type: 'token-quote-token-set',
+      },
+    ]
+  }
+  const nextQuoteTokenSet = findEvent('NextQuoteTokenSet')
+  if (nextQuoteTokenSet) {
+    const a = nextQuoteTokenSet.args as {
+      nextQuoteToken: Address.Address
+      updater: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(nextQuoteTokenSet)),
+        data: { nextQuoteToken: lc(a.nextQuoteToken), signer, updater: lc(a.updater) },
+        type: 'token-next-quote-token-set',
+      },
+    ]
+  }
+  const logoUriUpdated = findEvent('LogoURIUpdated')
+  if (logoUriUpdated) {
+    const a = logoUriUpdated.args as { newLogoURI: string; updater: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(logoUriUpdated)),
+        data: { logoUri: a.newLogoURI, signer, updater: lc(a.updater) },
+        type: 'token-logo-set',
+      },
+    ]
+  }
+  const roleMembershipUpdated = findEvent('RoleMembershipUpdated')
+  if (roleMembershipUpdated) {
+    const a = roleMembershipUpdated.args as {
+      account: Address.Address
+      hasRole: boolean
+      role: Hex.Hex
+      sender: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(roleMembershipUpdated)),
+        data: {
+          account: lc(a.account),
+          granted: a.hasRole,
+          role: hx(a.role),
+          sender: lc(a.sender),
+          signer,
+        },
+        type: 'role-membership-set',
+      },
+    ]
+  }
+  const roleAdminUpdated = findEvent('RoleAdminUpdated')
+  if (roleAdminUpdated) {
+    const a = roleAdminUpdated.args as {
+      newAdminRole: Hex.Hex
+      role: Hex.Hex
+      sender: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(roleAdminUpdated)),
+        data: {
+          newAdminRole: hx(a.newAdminRole),
+          role: hx(a.role),
+          sender: lc(a.sender),
+          signer,
+        },
+        type: 'role-admin-set',
+      },
+    ]
+  }
+
+  // Fee-manager token configuration.
+  const userTokenSet = findEvent('UserTokenSet')
+  if (userTokenSet) {
+    const a = userTokenSet.args as { token: Address.Address; user: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(userTokenSet)),
+        data: { signer, token: lc(a.token), user: lc(a.user) },
+        type: 'fee-user-token-set',
+      },
+    ]
+  }
+  const validatorTokenSet = findEvent('ValidatorTokenSet')
+  if (validatorTokenSet) {
+    const a = validatorTokenSet.args as { token: Address.Address; validator: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(validatorTokenSet)),
+        data: { signer, token: lc(a.token), validator: lc(a.validator) },
+        type: 'fee-validator-token-set',
+      },
+    ]
+  }
+
+  // TIP-403 policy registry (create wins over the member events it bundles).
+  const compoundPolicyCreated = findEvent('CompoundPolicyCreated')
+  if (compoundPolicyCreated) {
+    const a = compoundPolicyCreated.args as {
+      creator: Address.Address
+      mintRecipientPolicyId: bigint
+      policyId: bigint
+      recipientPolicyId: bigint
+      senderPolicyId: bigint
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(compoundPolicyCreated)),
+        data: {
+          creator: lc(a.creator),
+          mintRecipientPolicyId: a.mintRecipientPolicyId.toString(),
+          policyId: a.policyId.toString(),
+          recipientPolicyId: a.recipientPolicyId.toString(),
+          senderPolicyId: a.senderPolicyId.toString(),
+          signer,
+        },
+        type: 'compound-policy-created',
+      },
+    ]
+  }
+  const policyCreated = findEvent('PolicyCreated')
+  if (policyCreated) {
+    const a = policyCreated.args as {
+      policyId: bigint
+      policyType: number
+      updater: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(policyCreated)),
+        data: {
+          policyId: a.policyId.toString(),
+          policyType: Number(a.policyType),
+          signer,
+          updater: lc(a.updater),
+        },
+        type: 'policy-created',
+      },
+    ]
+  }
+  const policyAdminUpdated = findEvent('PolicyAdminUpdated')
+  if (policyAdminUpdated) {
+    const a = policyAdminUpdated.args as {
+      admin: Address.Address
+      policyId: bigint
+      updater: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(policyAdminUpdated)),
+        data: {
+          admin: lc(a.admin),
+          policyId: a.policyId.toString(),
+          signer,
+          updater: lc(a.updater),
+        },
+        type: 'policy-admin-set',
+      },
+    ]
+  }
+  const whitelistUpdated = findEvent('WhitelistUpdated')
+  if (whitelistUpdated) {
+    const a = whitelistUpdated.args as {
+      account: Address.Address
+      allowed: boolean
+      policyId: bigint
+      updater: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(whitelistUpdated)),
+        data: {
+          account: lc(a.account),
+          allowed: a.allowed,
+          policyId: a.policyId.toString(),
+          signer,
+          updater: lc(a.updater),
+        },
+        type: 'whitelist-updated',
+      },
+    ]
+  }
+  const blacklistUpdated = findEvent('BlacklistUpdated')
+  if (blacklistUpdated) {
+    const a = blacklistUpdated.args as {
+      account: Address.Address
+      policyId: bigint
+      restricted: boolean
+      updater: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(blacklistUpdated)),
+        data: {
+          account: lc(a.account),
+          policyId: a.policyId.toString(),
+          restricted: a.restricted,
+          signer,
+          updater: lc(a.updater),
+        },
+        type: 'blacklist-updated',
+      },
+    ]
+  }
+
+  // Address / nonce registry.
+  const masterRegistered = findEvent('MasterRegistered')
+  if (masterRegistered) {
+    const a = masterRegistered.args as { masterAddress: Address.Address; masterId: Hex.Hex }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(masterRegistered)),
+        data: { masterAddress: lc(a.masterAddress), masterId: hx(a.masterId), signer },
+        type: 'master-registered',
+      },
+    ]
+  }
+  const nonceIncremented = findEvent('NonceIncremented')
+  if (nonceIncremented) {
+    const a = nonceIncremented.args as {
+      account: Address.Address
+      newNonce: bigint
+      nonceKey: bigint
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(nonceIncremented)),
+        data: {
+          account: lc(a.account),
+          nonce: a.newNonce.toString(),
+          nonceKey: a.nonceKey.toString(),
+          signer,
+        },
+        type: 'nonce-incremented',
+      },
+    ]
+  }
+
+  // Access-key authorization witnesses.
+  const witnessRecorded = findEvent('KeyAuthorizationWitness')
+  if (witnessRecorded) {
+    const a = witnessRecorded.args as { account: Address.Address; witness: Hex.Hex }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(witnessRecorded)),
+        data: { account: lc(a.account), signer, witness: hx(a.witness) },
+        type: 'key-authorization-witness',
+      },
+    ]
+  }
+  const witnessBurned = findEvent('KeyAuthorizationWitnessBurned')
+  if (witnessBurned) {
+    const a = witnessBurned.args as { account: Address.Address; witness: Hex.Hex }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(witnessBurned)),
+        data: { account: lc(a.account), signer, witness: hx(a.witness) },
+        type: 'key-authorization-witness-burned',
+      },
+    ]
+  }
+
+  // Validator configuration (rotation supersedes the add/deactivate it bundles).
+  const validatorRotated = findEvent('ValidatorRotated')
+  if (validatorRotated) {
+    const a = validatorRotated.args as {
+      caller: Address.Address
+      deactivatedIndex: bigint
+      egress: string
+      index: bigint
+      ingress: string
+      newPublicKey: Hex.Hex
+      oldPublicKey: Hex.Hex
+      validatorAddress: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(validatorRotated)),
+        data: {
+          caller: lc(a.caller),
+          deactivatedIndex: a.deactivatedIndex.toString(),
+          egress: a.egress,
+          index: a.index.toString(),
+          ingress: a.ingress,
+          newPublicKey: hx(a.newPublicKey),
+          oldPublicKey: hx(a.oldPublicKey),
+          signer,
+          validator: lc(a.validatorAddress),
+        },
+        type: 'validator-rotated',
+      },
+    ]
+  }
+  const validatorAdded = findEvent('ValidatorAdded')
+  if (validatorAdded) {
+    const a = validatorAdded.args as {
+      egress: string
+      feeRecipient: Address.Address
+      index: bigint
+      ingress: string
+      publicKey: Hex.Hex
+      validatorAddress: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(validatorAdded)),
+        data: {
+          egress: a.egress,
+          feeRecipient: lc(a.feeRecipient),
+          index: a.index.toString(),
+          ingress: a.ingress,
+          publicKey: hx(a.publicKey),
+          signer,
+          validator: lc(a.validatorAddress),
+        },
+        type: 'validator-added',
+      },
+    ]
+  }
+  const validatorDeactivated = findEvent('ValidatorDeactivated')
+  if (validatorDeactivated) {
+    const a = validatorDeactivated.args as { index: bigint; validatorAddress: Address.Address }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(validatorDeactivated)),
+        data: { index: a.index.toString(), signer, validator: lc(a.validatorAddress) },
+        type: 'validator-deactivated',
+      },
+    ]
+  }
+  const validatorMigrated = findEvent('ValidatorMigrated')
+  if (validatorMigrated) {
+    const a = validatorMigrated.args as {
+      index: bigint
+      publicKey: Hex.Hex
+      validatorAddress: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(validatorMigrated)),
+        data: {
+          index: a.index.toString(),
+          publicKey: hx(a.publicKey),
+          signer,
+          validator: lc(a.validatorAddress),
+        },
+        type: 'validator-migrated',
+      },
+    ]
+  }
+  const validatorMigrationSkipped = findEvent('SkippedValidatorMigration')
+  if (validatorMigrationSkipped) {
+    const a = validatorMigrationSkipped.args as {
+      index: bigint
+      publicKey: Hex.Hex
+      validatorAddress: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(validatorMigrationSkipped)),
+        data: {
+          index: a.index.toString(),
+          publicKey: hx(a.publicKey),
+          signer,
+          validator: lc(a.validatorAddress),
+        },
+        type: 'validator-migration-skipped',
+      },
+    ]
+  }
+  const feeRecipientUpdated = findEvent('FeeRecipientUpdated')
+  if (feeRecipientUpdated) {
+    const a = feeRecipientUpdated.args as {
+      caller: Address.Address
+      feeRecipient: Address.Address
+      index: bigint
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(feeRecipientUpdated)),
+        data: {
+          caller: lc(a.caller),
+          feeRecipient: lc(a.feeRecipient),
+          index: a.index.toString(),
+          signer,
+        },
+        type: 'validator-fee-recipient-set',
+      },
+    ]
+  }
+  const ipAddressesUpdated = findEvent('IpAddressesUpdated')
+  if (ipAddressesUpdated) {
+    const a = ipAddressesUpdated.args as {
+      caller: Address.Address
+      egress: string
+      index: bigint
+      ingress: string
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(ipAddressesUpdated)),
+        data: {
+          caller: lc(a.caller),
+          egress: a.egress,
+          index: a.index.toString(),
+          ingress: a.ingress,
+          signer,
+        },
+        type: 'validator-ip-set',
+      },
+    ]
+  }
+  const validatorOwnershipTransferred = findEvent('ValidatorOwnershipTransferred')
+  if (validatorOwnershipTransferred) {
+    const a = validatorOwnershipTransferred.args as {
+      caller: Address.Address
+      index: bigint
+      newAddress: Address.Address
+      oldAddress: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(validatorOwnershipTransferred)),
+        data: {
+          caller: lc(a.caller),
+          index: a.index.toString(),
+          newAddress: lc(a.newAddress),
+          oldAddress: lc(a.oldAddress),
+          signer,
+        },
+        type: 'validator-ownership-transferred',
+      },
+    ]
+  }
+  const ownershipTransferred = findEvent('OwnershipTransferred')
+  if (ownershipTransferred) {
+    const a = ownershipTransferred.args as {
+      newOwner: Address.Address
+      oldOwner: Address.Address
+    }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(ownershipTransferred)),
+        data: { newOwner: lc(a.newOwner), oldOwner: lc(a.oldOwner), signer },
+        type: 'ownership-transferred',
+      },
+    ]
+  }
+  const rotationEpochSet = findEvent('NetworkIdentityRotationEpochSet')
+  if (rotationEpochSet) {
+    const a = rotationEpochSet.args as { nextEpoch: bigint; previousEpoch: bigint }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(rotationEpochSet)),
+        data: {
+          nextEpoch: a.nextEpoch.toString(),
+          previousEpoch: a.previousEpoch.toString(),
+          signer,
+        },
+        type: 'network-identity-rotation-epoch-set',
+      },
+    ]
+  }
+  const initialized = findEvent('Initialized')
+  if (initialized) {
+    const a = initialized.args as { height: bigint }
+    return [
+      {
+        ...itemBase(logIndexOfEvent(initialized)),
+        data: { height: a.height.toString(), signer },
+        type: 'initialized',
+      },
+    ]
+  }
+
+  // Default: plain transfer (excluding transfers to the fee manager).
+  const userTransfers = transfers.filter(
+    (e) => !Address.isEqual((e.args as { to: Address.Address }).to, Addresses.feeManager),
+  )
+  if (userTransfers.length > 0) {
+    const t = userTransfers[0]!
+    const args = t.args as {
+      amount: bigint
+      from: Address.Address
+      memo?: Hex.Hex | undefined
+      to: Address.Address
+    }
+    const to = args.to.toLowerCase() as Address.Address
+    const from = args.from.toLowerCase() as Address.Address
+    const rawMemo = t.eventName === 'TransferWithMemo' ? args.memo : undefined
+    // The raw memo (not the suppressed display string) carries the MPP
+    // attribution fingerprint, so resolve the service name from it.
+    const memo = rawMemo ? Transfers.memoToString(rawMemo) : undefined
+    const attribution = Mpp.resolve({ fingerprintMap, memo: rawMemo })
+    const sourceToken = token(args.amount, t.address as Address.Address)
+    if (Address.isEqual(to, viewer))
+      return [
+        transfer(itemBase(logIndexOfEvent(t)), blockNum, {
+          attribution,
+          direction: 'in',
+          memo,
+          recipient: viewer,
+          sender: from,
+          sourceToken,
+        }),
+        ...accessKeyItems,
+      ]
+    return [
+      transfer(itemBase(logIndexOfEvent(t)), blockNum, {
+        attribution,
+        direction: 'out',
+        memo,
+        recipient: to,
+        sender: from,
+        signer,
+        sourceToken,
+      }),
+      ...accessKeyItems,
+    ]
+  }
+
+  // Pure access-key tx (no transfer / mint / burn / etc.).
+  if (accessKeyItems.length > 0) return accessKeyItems
+
+  // Unclassified: a tx the address sent or paid for whose logs matched no known
+  // classifier. Surface it honestly as an `unknown` item carrying every log
+  // (decoded when possible), rather than fabricating a zero transfer.
+  return [unknown(itemBase(minLogIndex), { events: buildTxEvents(rows, events), signer })]
+}
+
+/** Extracts the block-wide log index from a decoded viem event. */
+function logIndexOfEvent(event: { logIndex: number }): number {
+  return event.logIndex
+}
+
+/**
+ * Builds a `transfer` item whose `data` is the `Transfer` API resource plus the
+ * feed-only `direction`/`memo`/`attribution`/`signer` fields. Optional fields
+ * are omitted when absent (`exactOptionalPropertyTypes`).
+ */
+function transfer(
+  base: Base,
+  blockNumber: number,
+  data: {
+    attribution?: string | undefined
+    destinationToken?: Token | undefined
+    direction: 'in' | 'out'
+    memo?: string | undefined
+    recipient: Address.Address
+    sender: Address.Address
+    signer?: 'self' | Address.Address | undefined
+    sourceToken: Token
+  },
+): Extract<RawItem, { type: 'transfer' }> {
+  return {
+    ...base,
+    data: {
+      ...(data.attribution ? { attribution: data.attribution } : {}),
+      blockNumber,
+      ...(data.destinationToken ? { destinationToken: data.destinationToken } : {}),
+      direction: data.direction,
+      ...(data.memo ? { memo: data.memo } : {}),
+      recipient: data.recipient,
+      sender: data.sender,
+      ...(data.signer ? { signer: data.signer } : {}),
+      sourceToken: data.sourceToken,
+      timestamp: base.timestamp,
+      transactionHash: base.transactionHash,
+    },
+    type: 'transfer',
+  }
+}
+
+/** One entry in an item's `events` capture: a log, decoded when possible (derived from the schema). */
+type TxEvent = NonNullable<Item['events']>[number]
+
+/** The structural slice of a decoded `parseEventLogs` event that {@link buildTxEvents} reads. */
+type DecodedEvent = { args: unknown; eventName: string; logIndex: number }
+
+/**
+ * Builds an `unknown` item for a transaction the address sent or paid for that
+ * did not match any known classifier. Carries the real `transactionHash`/
+ * `timestamp` plus every log of the transaction in the top-level `events`
+ * array (decoded into `eventName`/`args`/`title` when the log matched a known
+ * `viem/tempo` ABI, otherwise just the raw `topics`/`data`), so no log is ever
+ * silently dropped.
+ */
+function unknown(
+  base: Base,
+  data: { events: TxEvent[]; signer: 'self' | Address.Address },
+): Extract<RawItem, { type: 'unknown' }> {
+  return { ...base, data: { signer: data.signer }, events: data.events, type: 'unknown' }
+}
+
+/** Decodes a group's raw rows into `viem/tempo` events via `parseEventLogs` (non-strict). */
+function decodeRows(rows: readonly Row[]) {
+  const viemLogs: Log[] = rows.map((r) => ({
+    address: r.logAddress as `0x${string}`,
+    blockHash: '0x0' as Hex.Hex,
+    blockNumber: BigInt(r.blockNum),
+    data: (r.data ?? '0x') as Hex.Hex,
+    logIndex: r.logIdx,
+    removed: false,
+    topics: [r.selector, r.topic1, r.topic2, r.topic3].filter(Boolean) as [Hex.Hex, ...Hex.Hex[]],
+    transactionHash: r.txHash as `0x${string}`,
+    transactionIndex: r.txIdx,
+  }))
+  return parseEventLogs({ abi: [...Abis.abis], logs: viemLogs, strict: false })
+}
+
+/**
+ * Builds the full per-transaction `events` capture: one entry per raw log,
+ * enriched with `eventName`/`args`/`title` when that log decoded into a known
+ * event. Decoded entries are matched to their raw log by block-wide log index,
+ * so the result covers every log (decoded or not) exactly once.
+ */
+function buildTxEvents(rows: readonly Row[], decoded: readonly DecodedEvent[]): TxEvent[] {
+  const decodedByIndex = new Map(decoded.map((event) => [event.logIndex, event]))
+  return rows
+    .map((row) => {
+      const base = {
+        address: row.logAddress,
+        data: (row.data ?? '0x') as Hex.Hex,
+        logIndex: row.logIdx,
+        topics: [row.selector, row.topic1, row.topic2, row.topic3].filter(
+          (topic): topic is Hex.Hex => topic !== null,
+        ),
+      }
+      const event = decodedByIndex.get(row.logIdx)
+      if (!event) return base
+      return {
+        ...base,
+        args: (jsonSafe(event.args) ?? {}) as Record<string, unknown>,
+        eventName: event.eventName,
+        ...(titleByEventName[event.eventName] ? { title: titleByEventName[event.eventName] } : {}),
+      }
+    })
+    .sort((a, b) => a.logIndex - b.logIndex)
+}
+
+/**
+ * Recursively converts decoded-event values into JSON-serializable form: bigints
+ * become decimal strings, address-shaped strings are lowercased to match the
+ * API's address convention (viem returns them checksummed), arrays/objects are
+ * walked, everything else passes through. Applied to `parseEventLogs` args
+ * before they cross the API boundary.
+ */
+function jsonSafe(value: unknown): unknown {
+  if (typeof value === 'bigint') return value.toString()
+  if (typeof value === 'string')
+    return /^0x[0-9a-fA-F]{40}$/.test(value) ? value.toLowerCase() : value
+  if (Array.isArray(value)) return value.map(jsonSafe)
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const [key, val] of Object.entries(value)) out[key] = jsonSafe(val)
+    return out
+  }
+  return value
+}
+
+/** Lowercases a TIDX address column, defaulting to the zero address. */
+function lower(value: unknown): Address.Address {
+  return (Value.toText(value)?.toLowerCase() ?? zeroAddress) as Address.Address
+}
+
+/** Lowercases a TIDX transaction hash column, defaulting to `0x` when absent. */
+function lowerHash(value: unknown): Hex.Hex {
+  return (Value.toText(value)?.toLowerCase() ?? '0x') as Hex.Hex
+}
+
+/** Lowercases an optional TIDX address column, or null when absent. */
+function lowerOrNull(value: unknown): Address.Address | null {
+  const text = Value.toText(value)
+  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 {
+  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>>
+  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>>
+
+/**
+ * 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
+  const addresses = new Set<Address.Address>()
+  for (const item of items) collectTokens(item, addresses)
+  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] as const)
+          .catch(() => [address.toLowerCase(), undefined] as const),
+      ),
+    ),
+  )
+  const byAddress = new Map(resolved)
+  for (const item of items) enrichItem(item, byAddress)
+}
+
+declare namespace enrichTokens {
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    items: readonly Item[]
+  }
+}
+
+/** 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>>
+  for (const key of tokenKeys) {
+    const t = data[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.
+    data[key] = {
+      ...t,
+      currency: meta.currency,
+      decimals: meta.decimals,
+      name: meta.name,
+      symbol: meta.symbol,
+    }
+  }
+}
+
+/**
+ * Folds adjacent items signed by the same access key on the same UTC calendar
+ * day into a single `group` entry. Self-signed items pass through untouched.
+ * 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
+
+  for (const item of items) {
+    const itemSigner = signerOf(item)
+    if (itemSigner !== 'self') {
+      if (
+        currentGroup &&
+        Address.isEqual(currentGroup.signer, itemSigner) &&
+        sameCalendarDay(currentGroup.items[0]!.timestamp, item.timestamp)
+      ) {
+        currentGroup.items.push(item)
+        if (currentGroup.items.length >= maxGroupSize) {
+          entries.push(flushGroup(currentGroup))
+          currentGroup = null
+        }
+      } else {
+        if (currentGroup) entries.push(flushGroup(currentGroup))
+        currentGroup = { items: [item], signer: itemSigner }
+      }
+    } else {
+      if (currentGroup) {
+        entries.push(flushGroup(currentGroup))
+        currentGroup = null
+      }
+      entries.push(item)
+    }
+  }
+
+  if (currentGroup) entries.push(flushGroup(currentGroup))
+  return entries
+}
+
+/** The access-key signer of an item, or `self` when it has no access-key signer. */
+function signerOf(item: Item): '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 {
+  if (group.items.length === 1) return group.items[0]!
+  const firstItem = group.items[0]!
+  const lastItem = group.items[group.items.length - 1]!
+  return {
+    data: { items: group.items, signer: group.signer },
+    perspective: firstItem.perspective,
+    id: `${firstItem.id}..${lastItem.id}:${group.items.length}`,
+    timestamp: firstItem.timestamp,
+    title: 'Group',
+    type: 'group',
+  }
+}
+
+/** Whether two ISO 8601 timestamps fall on the same UTC calendar day. */
+function sameCalendarDay(a: string, b: string): boolean {
+  const da = new Date(a)
+  const db = new Date(b)
+  return (
+    da.getUTCFullYear() === db.getUTCFullYear() &&
+    da.getUTCMonth() === db.getUTCMonth() &&
+    da.getUTCDate() === db.getUTCDate()
+  )
+}