tapimo 0.0.0 → 0.0.2

package/src/apps/activities.test.ts

@@ -0,0 +1,1020 @@
+import { Address, Hex } from 'ox'
+import { encodeAbiParameters, encodeEventTopics } from 'viem'
+import { Abis } from 'viem/tempo'
+
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
+import * as Store from '../internal/Store.js'
+import * as Activities from './activities.js'
+
+/**
+ * Real Tempo (Moderato) accounts, each exercising specific activity types.
+ * Discovered by scanning indexed `logs` for the event each type classifies
+ * from, then confirming the classified feed through the live endpoint. If the
+ * testnet prunes this history, rediscover replacements the same way.
+ */
+const liveAccounts = {
+  // Payment-channel close (session-closed), folded into access-key groups.
+  channel: '0x5217c502adf3c96a9551770af4caa5f5144a6984',
+  // TokenCreated + Mint + Transfer.
+  creator: '0x253fb3bf1e3d75ad6ee1554f68f4ea0568f7d24e',
+  // Token burns.
+  burner: '0x69519497b59bd64e109d993157d45f14455cc7e6',
+  // KeyAuthorized + KeyRevoked + Approval (+ transfer/mint/exchange).
+  keychain: '0xfe776fd28e06ecc71a157398b2c9991318f1ea2e',
+  // Swaps through the stablecoin DEX (output kept, so it stays a plain `swap`).
+  swapper: '0x7f4e7fdd75e4c5beb77d0eb223823d3a5a9865c0',
+} as const
+
+const runtime = Runtime.get()
+const localAccounts = runtime.fixtures?.activityAccounts
+const accounts =
+  runtime.mode === 'localnet' && localAccounts
+    ? {
+        channel: localAccounts.keychain,
+        creator: localAccounts.creator,
+        burner: localAccounts.burner,
+        keychain: localAccounts.keychain,
+        swapper: localAccounts.swapper,
+      }
+    : liveAccounts
+
+/** The account expected to surface each activity type. */
+const coverage =
+  runtime.mode === 'localnet'
+    ? {
+        approval: accounts.keychain,
+        burn: accounts.burner,
+        mint: accounts.creator,
+        'token-created': accounts.creator,
+        transfer: accounts.creator,
+      }
+    : {
+        'access-key-created': accounts.keychain,
+        'access-key-revoked': accounts.keychain,
+        approval: accounts.keychain,
+        burn: accounts.burner,
+        mint: accounts.creator,
+        'session-closed': accounts.channel,
+        swap: accounts.swapper,
+        'token-created': accounts.creator,
+        transfer: accounts.creator,
+      }
+
+const client = TestApp.client()
+
+/**
+ * Requests an address's activity page, retrying transient upstream `502`s
+ * (TIDX surfaces a busy ClickHouse planner as a `422` the route maps to `502`).
+ */
+async function request(address: string, query: Record<string, string> = {}) {
+  let response = await activitiesRequest(address, query)
+  for (let attempt = 0; attempt < 2 && response.status !== 200; attempt++)
+    response = await activitiesRequest(address, query)
+  return response
+}
+
+function activitiesRequest(address: string, query: Record<string, string>) {
+  return client.v1.addresses[':address'].activities.$get(
+    { param: { address: address as Hex.Hex }, query: { limit: '50', ...query } },
+    TestApp.auth,
+  )
+}
+
+/** Requests and schema-validates an address's activity page. */
+async function activities(address: string, query: Record<string, string> = {}) {
+  return TestApp.json(
+    await request(address, query),
+    Activities.schema.getAddressActivities.Response,
+  )
+}
+
+/** Finds an entry (or grouped item) of the given type, searching inside groups. */
+function find(items: readonly Activities.Entry[], type: string): Activities.Entry | undefined {
+  for (const entry of items) {
+    if (entry.type === type) return entry
+    if (entry.type === 'group') {
+      const item = entry.data.items.find((i) => i.type === type)
+      if (item) return item
+    }
+  }
+  return undefined
+}
+
+describe('GET /addresses/:address/activities', () => {
+  test('returns a newest-first, schema-valid feed with timing', async () => {
+    const response = await request(accounts.keychain, { limit: '10' })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('address_activities;dur=')).toBe(true)
+
+    const body = await TestApp.json(response, Activities.schema.getAddressActivities.Response)
+    expect(Array.isArray(body.data)).toBe(true)
+    expect(body.nextCursor === null || typeof body.nextCursor === 'string').toBe(true)
+
+    // Entries are ordered newest-first by timestamp (ISO 8601 sorts
+    // lexicographically the same as chronologically).
+    const timestamps = body.data.map((entry) => entry.timestamp)
+    expect(timestamps.every((ts, i) => i === 0 || timestamps[i - 1]! >= ts)).toBe(true)
+  })
+
+  test.each(Object.entries(coverage))('classifies %s activity', async (type, address) => {
+    const body = await activities(address)
+    expect(find(body.data, type)).toBeDefined()
+  })
+
+  test('transfer data mirrors the `Transfer` resource', async () => {
+    const transfer = find((await activities(accounts.creator)).data, 'transfer')
+    expect(transfer?.type).toBe('transfer')
+    if (transfer?.type !== 'transfer') return
+    expect(['in', 'out']).toContain(transfer.data.direction)
+    expect(transfer.data.transactionHash).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(typeof transfer.data.blockNumber).toBe('number')
+    expect(transfer.data.sourceToken.address).toMatch(/^0x[0-9a-f]{40}$/)
+    expect(transfer.data.sourceToken.amount).toMatch(/^\d+$/)
+  })
+
+  test.skipIf(runtime.mode === 'localnet')('swap data carries both sides of the swap', async () => {
+    const swap = find((await activities(accounts.swapper)).data, 'swap')
+    expect(swap?.type).toBe('swap')
+    if (swap?.type !== 'swap') return
+    expect(swap.data.sourceToken.address).toMatch(/^0x[0-9a-f]{40}$/)
+    expect(swap.data.destinationToken.address).toMatch(/^0x[0-9a-f]{40}$/)
+  })
+
+  test.skipIf(runtime.mode !== 'localnet')(
+    'surfaces a cross-token transfer as outgoing in the sender feed',
+    async () => {
+      const crossToken = runtime.fixtures?.crossTokenTransfer
+      expect(crossToken).toBeDefined()
+      if (!crossToken) return
+
+      const { data } = await activities(crossToken.sender)
+      const transfer = data.find(
+        (entry) =>
+          entry.type === 'transfer' &&
+          entry.transactionHash === crossToken.hash &&
+          entry.data.destinationToken?.address === crossToken.destinationToken,
+      )
+      expect(transfer?.type).toBe('transfer')
+      if (transfer?.type !== 'transfer') return
+      expect(transfer.data.direction).toBe('out')
+      expect(transfer.data.sender).toBe(crossToken.sender)
+      expect(transfer.data.recipient).toBe(crossToken.recipient)
+      expect(transfer.data.sourceToken.address).toBe(crossToken.sourceToken)
+      expect(transfer.data.destinationToken?.address).toBe(crossToken.destinationToken)
+    },
+  )
+
+  test.skipIf(runtime.mode !== 'localnet')(
+    'surfaces a cross-token transfer as a plain incoming delivery in the recipient feed',
+    async () => {
+      const crossToken = runtime.fixtures?.crossTokenTransfer
+      expect(crossToken).toBeDefined()
+      if (!crossToken) return
+
+      // The recipient feed is built only from the inbound delivery leg (the
+      // sender's `from`/`fee_payer` rows, which carry the swap, are out of
+      // scope for the recipient). So the recipient sees an ordinary incoming
+      // transfer of the token they received, with no cross-token framing: the
+      // delivered token is the `sourceToken` and there is no `destinationToken`.
+      const { data } = await activities(crossToken.recipient)
+      const transfer = data.find(
+        (entry) => entry.type === 'transfer' && entry.transactionHash === crossToken.hash,
+      )
+      expect(transfer?.type).toBe('transfer')
+      if (transfer?.type !== 'transfer') return
+      expect(transfer.data.direction).toBe('in')
+      expect(transfer.data.sender).toBe(crossToken.sender)
+      expect(transfer.data.recipient).toBe(crossToken.recipient)
+      expect(transfer.data.sourceToken.address).toBe(crossToken.destinationToken)
+      expect(transfer.data.destinationToken).toBeUndefined()
+    },
+  )
+
+  test.skipIf(runtime.mode === 'localnet')(
+    'folds consecutive access-key items into a group when group=true',
+    async () => {
+      const group = find((await activities(accounts.channel, { group: 'true' })).data, 'group')
+      expect(group?.type).toBe('group')
+      if (group?.type !== 'group') return
+      expect(group.data.items.length).toBeGreaterThan(1)
+      expect(group.data.signer).toMatch(/^0x[0-9a-f]{40}$/)
+    },
+  )
+
+  test('returns every item at the root by default (no group entries)', async () => {
+    const body = await activities(accounts.channel)
+    expect(body.data.every((entry) => entry.type !== 'group')).toBe(true)
+  })
+
+  test('paginates with an opaque cursor', async () => {
+    const first = await activities(accounts.keychain, { limit: '5' })
+    if (!first.nextCursor) return
+    const second = await activities(accounts.keychain, { limit: '5', cursor: first.nextCursor })
+    expect(Array.isArray(second.data)).toBe(true)
+  })
+})
+
+/** Resolves a real transaction hash from an address's (non-grouped) activity feed. */
+async function firstTransactionHash(address: string): Promise<Hex.Hex | undefined> {
+  const { data } = await activities(address)
+  for (const entry of data) if (entry.type !== 'group') return entry.transactionHash
+  return undefined
+}
+
+function transactionActivitiesRequest(transactionHash: string, query: Record<string, string> = {}) {
+  return client.v1.transactions[':transactionHash'].activities.$get(
+    { param: { transactionHash: transactionHash as Hex.Hex }, query },
+    TestApp.auth,
+  )
+}
+
+describe('GET /transactions/:transactionHash/activities', () => {
+  test('classifies the activity on a real transaction', async () => {
+    // Resolve a real transaction hash from the address feed, then classify it
+    // through the transaction-scoped endpoint.
+    const transactionHash = await firstTransactionHash(accounts.creator)
+    expect(transactionHash).toBeDefined()
+    if (!transactionHash) return
+
+    const response = await transactionActivitiesRequest(transactionHash)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('transaction_activities;dur=')).toBe(
+      true,
+    )
+
+    const body = await TestApp.json(response, Activities.schema.getTransactionActivities.Response)
+    expect(body.data.length).toBeGreaterThan(0)
+    // Every classified item belongs to the requested transaction.
+    expect(body.data.every((item) => item.transactionHash === transactionHash)).toBe(true)
+  })
+
+  test('attaches the full event set when logs=true', async () => {
+    const transactionHash = await firstTransactionHash(accounts.creator)
+    if (!transactionHash) return
+
+    const body = await TestApp.json(
+      await transactionActivitiesRequest(transactionHash, { logs: 'true' }),
+      Activities.schema.getTransactionActivities.Response,
+    )
+    expect(body.data.some((item) => Array.isArray(item.events) && item.events.length > 0)).toBe(
+      true,
+    )
+  })
+
+  test.skipIf(runtime.mode !== 'localnet')(
+    'classifies a seeded cross-token transfer with both source and destination tokens',
+    async () => {
+      const crossToken = runtime.fixtures?.crossTokenTransfer
+      expect(crossToken).toBeDefined()
+      if (!crossToken) return
+
+      const body = await TestApp.json(
+        await transactionActivitiesRequest(crossToken.hash),
+        Activities.schema.getTransactionActivities.Response,
+      )
+      // The swap and its onward delivery leg fold into a single cross-token
+      // `transfer`; there is no separate `swap` item.
+      expect(body.data.some((item) => item.type === 'swap')).toBe(false)
+      const transfer = body.data.find((item) => item.type === 'transfer')
+      expect(transfer?.type).toBe('transfer')
+      if (transfer?.type !== 'transfer') return
+      expect(transfer.data.direction).toBe('out')
+      expect(transfer.data.recipient).toBe(crossToken.recipient)
+      expect(transfer.data.sourceToken.address).toBe(crossToken.sourceToken)
+      expect(transfer.data.destinationToken?.address).toBe(crossToken.destinationToken)
+    },
+  )
+
+  test('404s for an unknown transaction hash', async () => {
+    const response = await transactionActivitiesRequest(`0x${'0'.repeat(64)}`)
+    expect(response.status).toBe(404)
+  })
+})
+
+describe('Activities.list classification', () => {
+  const viewer = '0x1111111111111111111111111111111111111111' as Address.Address
+
+  /** A memory store pre-seeded so the MPP directory fetch never hits the network. */
+  function store() {
+    const store = Store.memory()
+    void store.put('mpp-services:v1', JSON.stringify({}))
+    return store
+  }
+
+  /** A {@link Activities.Provider} that returns a fixed set of rows once. */
+  function provider(rows: Activities.Row[]): Activities.Provider {
+    return {
+      cursorForGroup: (group) => `${group.blockNum}:${group.txIdx}`,
+      fetchRows: async () => ({ rows }),
+    }
+  }
+
+  test('classifies an unrecognized Q1 tx as `unknown` with decoded events', async () => {
+    // A gas-fee Transfer to the fee manager decodes as a known `Transfer`
+    // event, but the classifier excludes fee-manager transfers, so the tx has
+    // no classifiable activity and falls through to `unknown`.
+    const token = '0x2222222222222222222222222222222222222222' as Address.Address
+    const feeManager = '0xfeec000000000000000000000000000000000000'
+    const transferSelector = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
+    const pad = (a: string) => `0x${a.slice(2).padStart(64, '0')}`
+    const { items } = await Activities.list(
+      provider([
+        {
+          blockNum: 100,
+          blockTimestamp: 1_700_000_000,
+          data: `0x${(5).toString(16).padStart(64, '0')}`,
+          feePayer: null,
+          logAddress: token,
+          logIdx: 0,
+          selector: transferSelector,
+          source: 'q1',
+          topic1: pad(viewer),
+          topic2: pad(feeManager),
+          topic3: null,
+          txHash: `0x${'a'.repeat(64)}` as Hex.Hex,
+          txIdx: 0,
+          txSender: viewer,
+        },
+      ]),
+      { address: viewer, store: store() },
+    )
+
+    expect(items).toHaveLength(1)
+    const item = items[0]!
+    expect(item.type).toBe('unknown')
+    if (item.type !== 'unknown') return
+    expect(item.data.signer).toBe('self')
+    expect(item.transactionHash).toBe(`0x${'a'.repeat(64)}`)
+    expect(item.events).toHaveLength(1)
+    const event = item.events![0]!
+    expect(event.eventName).toBe('Transfer')
+    expect(event.args!['amount']).toBe('5')
+    // Addresses are normalized to lowercase (viem decodes them checksummed).
+    expect(event.args!['from']).toBe(viewer)
+    expect(event.args!['to']).toBe(feeManager)
+  })
+
+  test('captures undecoded logs on an `unknown` tx so no log is dropped', async () => {
+    // A log whose selector is not in any known Tempo ABI cannot decode, so it
+    // would be invisible without the raw `logs` capture.
+    const contract = '0x3333333333333333333333333333333333333333' as Address.Address
+    const unknownSelector = `0x${'b'.repeat(64)}`
+    const pad = (a: string) => `0x${a.slice(2).padStart(64, '0')}`
+    const { items } = await Activities.list(
+      provider([
+        {
+          blockNum: 100,
+          blockTimestamp: 1_700_000_000,
+          data: '0x1234',
+          feePayer: null,
+          logAddress: contract,
+          logIdx: 2,
+          selector: unknownSelector,
+          source: 'q1',
+          topic1: pad(viewer),
+          topic2: null,
+          topic3: null,
+          txHash: `0x${'c'.repeat(64)}` as Hex.Hex,
+          txIdx: 0,
+          txSender: viewer,
+        },
+      ]),
+      { address: viewer, store: store() },
+    )
+
+    expect(items).toHaveLength(1)
+    const item = items[0]!
+    expect(item.type).toBe('unknown')
+    if (item.type !== 'unknown') return
+    // The undecoded log is surfaced as a raw event entry (no `eventName`/`args`).
+    expect(item.events).toHaveLength(1)
+    const log = item.events![0]!
+    expect(log.eventName).toBeUndefined()
+    expect(log.args).toBeUndefined()
+    expect(log.address).toBe(contract)
+    expect(log.logIndex).toBe(2)
+    expect(log.data).toBe('0x1234')
+    expect(log.topics).toEqual([unknownSelector, pad(viewer)])
+  })
+})
+
+describe('Activities.list precompile classification', () => {
+  const viewer = '0x1111111111111111111111111111111111111111' as Address.Address
+  const tokenA = '0x2222222222222222222222222222222222222222' as Address.Address
+  const stablecoinDex = '0xdec0000000000000000000000000000000000000' as Address.Address
+  const feeManager = '0xfeec000000000000000000000000000000000000' as Address.Address
+  const accountKeychain = '0xaaaaaaaa00000000000000000000000000000000' as Address.Address
+  const channelReserve = '0x4d50500000000000000000000000000000000000' as Address.Address
+  const tip20Factory = '0x20fc000000000000000000000000000000000000' as Address.Address
+  const txHash = `0x${'b'.repeat(64)}` as Hex.Hex
+
+  function store() {
+    const store = Store.memory()
+    void store.put('mpp-services:v1', JSON.stringify({}))
+    return store
+  }
+
+  function provider(rows: Activities.Row[]): Activities.Provider {
+    return {
+      cursorForGroup: (group) => `${group.blockNum}:${group.txIdx}`,
+      fetchRows: async () => ({ rows }),
+    }
+  }
+
+  /** Builds a Q1 log row for `eventName` by ABI-encoding its indexed topics and data. */
+  function logRow(options: {
+    address: Address.Address
+    args: Record<string, unknown>
+    eventName: string
+    logIdx: number
+  }): Activities.Row {
+    type Param = { indexed?: boolean; name?: string; type: string }
+    const event = Abis.abis.find((a) => a.type === 'event' && a.name === options.eventName) as {
+      inputs: readonly Param[]
+    }
+    const topics = encodeEventTopics({
+      abi: Abis.abis,
+      eventName: options.eventName as never,
+      args: options.args as never,
+    }) as (string | null)[]
+    const dataInputs = event.inputs.filter((i) => !i.indexed)
+    const data = encodeAbiParameters(
+      dataInputs,
+      dataInputs.map((i) => options.args[i.name!]),
+    )
+    return {
+      blockNum: 100,
+      blockTimestamp: 1_700_000_000,
+      data,
+      feePayer: null,
+      logAddress: options.address,
+      logIdx: options.logIdx,
+      selector: topics[0] ?? null,
+      source: 'q1',
+      topic1: topics[1] ?? null,
+      topic2: topics[2] ?? null,
+      topic3: topics[3] ?? null,
+      txHash,
+      txIdx: 0,
+      txSender: viewer,
+    }
+  }
+
+  /** A Q1 TIP-20 `Transfer` log row, used to back channel token recovery. */
+  function transferRow(options: {
+    from: Address.Address
+    logIdx: number
+    to: Address.Address
+    token: Address.Address
+    value: bigint
+  }): Activities.Row {
+    return logRow({
+      address: options.token,
+      args: { amount: options.value, from: options.from, to: options.to },
+      eventName: 'Transfer',
+      logIdx: options.logIdx,
+    })
+  }
+
+  async function classify(rows: Activities.Row[]) {
+    const { items } = await Activities.list(provider(rows), { address: viewer, store: store() })
+    return items
+  }
+
+  test('classifies ChannelOpened as `channel-opened` with the deposit token', async () => {
+    const items = await classify([
+      logRow({
+        address: channelReserve,
+        args: {
+          authorizedSigner: viewer,
+          channelId: `0x${'c'.repeat(64)}`,
+          deposit: 1000n,
+          expiringNonceHash: `0x${'0'.repeat(64)}`,
+          operator: viewer,
+          payee: tokenA,
+          payer: viewer,
+          salt: `0x${'0'.repeat(64)}`,
+          token: tokenA,
+        },
+        eventName: 'ChannelOpened',
+        logIdx: 0,
+      }),
+    ])
+    expect(items).toHaveLength(1)
+    expect(items[0]!.type).toBe('channel-opened')
+    if (items[0]!.type !== 'channel-opened') return
+    expect(items[0]!.data.sourceToken.amount).toBe('1000')
+    expect(items[0]!.data.payer).toBe(viewer)
+  })
+
+  test('classifies TopUp as `channel-funded`, recovering token from the paired transfer', async () => {
+    const items = await classify([
+      transferRow({ from: viewer, logIdx: 0, to: channelReserve, token: tokenA, value: 500n }),
+      logRow({
+        address: channelReserve,
+        args: {
+          additionalDeposit: 500n,
+          channelId: `0x${'c'.repeat(64)}`,
+          newDeposit: 1500n,
+          payee: tokenA,
+          payer: viewer,
+        },
+        eventName: 'TopUp',
+        logIdx: 1,
+      }),
+    ])
+    expect(items).toHaveLength(1)
+    expect(items[0]!.type).toBe('channel-funded')
+    if (items[0]!.type !== 'channel-funded') return
+    expect(items[0]!.data.sourceToken.address).toBe(tokenA)
+    expect(items[0]!.data.sourceToken.amount).toBe('500')
+  })
+
+  test('classifies Settled as `channel-settled`', async () => {
+    const payee = '0x3333333333333333333333333333333333333333' as Address.Address
+    const items = await classify([
+      transferRow({ from: channelReserve, logIdx: 0, to: payee, token: tokenA, value: 250n }),
+      logRow({
+        address: channelReserve,
+        args: {
+          channelId: `0x${'c'.repeat(64)}`,
+          cumulativeAmount: 250n,
+          deltaPaid: 250n,
+          newSettled: 250n,
+          payee,
+          payer: viewer,
+        },
+        eventName: 'Settled',
+        logIdx: 1,
+      }),
+    ])
+    expect(items[0]!.type).toBe('channel-settled')
+    if (items[0]!.type !== 'channel-settled') return
+    expect(items[0]!.data.sourceToken.amount).toBe('250')
+    expect(items[0]!.data.payee).toBe(payee)
+  })
+
+  test('classifies ChannelClosed as `channel-closed` with payout and refund', async () => {
+    const payee = '0x3333333333333333333333333333333333333333' as Address.Address
+    const items = await classify([
+      transferRow({ from: channelReserve, logIdx: 0, to: payee, token: tokenA, value: 600n }),
+      transferRow({ from: channelReserve, logIdx: 1, to: viewer, token: tokenA, value: 400n }),
+      logRow({
+        address: channelReserve,
+        args: {
+          channelId: `0x${'c'.repeat(64)}`,
+          payee,
+          payer: viewer,
+          refundedToPayer: 400n,
+          settledToPayee: 600n,
+        },
+        eventName: 'ChannelClosed',
+        logIdx: 2,
+      }),
+    ])
+    expect(items[0]!.type).toBe('channel-closed')
+    if (items[0]!.type !== 'channel-closed') return
+    expect(items[0]!.data.sourceToken?.amount).toBe('600')
+    expect(items[0]!.data.refund?.amount).toBe('400')
+  })
+
+  test('classifies CloseRequestCancelled as `channel-close-cancelled`', async () => {
+    const payee = '0x3333333333333333333333333333333333333333' as Address.Address
+    const items = await classify([
+      logRow({
+        address: channelReserve,
+        args: { channelId: `0x${'c'.repeat(64)}`, payee, payer: viewer },
+        eventName: 'CloseRequestCancelled',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('channel-close-cancelled')
+    if (items[0]!.type !== 'channel-close-cancelled') return
+    expect(items[0]!.data.channelId).toBe(`0x${'c'.repeat(64)}`)
+    expect(items[0]!.data.payee).toBe(payee)
+    expect(items[0]!.data.payer).toBe(viewer)
+  })
+
+  test('classifies OrderPlaced as `order-placed`', async () => {
+    const items = await classify([
+      transferRow({ from: viewer, logIdx: 0, to: stablecoinDex, token: tokenA, value: 1000n }),
+      logRow({
+        address: stablecoinDex,
+        args: {
+          amount: 1000n,
+          flipTick: 0,
+          isBid: true,
+          isFlipOrder: false,
+          maker: viewer,
+          orderId: 42n,
+          tick: 5,
+          token: tokenA,
+        },
+        eventName: 'OrderPlaced',
+        logIdx: 1,
+      }),
+    ])
+    expect(items[0]!.type).toBe('order-placed')
+    if (items[0]!.type !== 'order-placed') return
+    expect(items[0]!.data.orderId).toBe('42')
+    expect(items[0]!.data.side).toBe('bid')
+    expect(items[0]!.data.tick).toBe(5)
+  })
+
+  test('folds a swap plus onward delivery into one cross-token `transfer`', async () => {
+    const tokenB = '0x5555555555555555555555555555555555555555' as Address.Address
+    const recipient = '0x7777777777777777777777777777777777777777' as Address.Address
+    const items = await classify([
+      // Source token spent into the DEX.
+      transferRow({ from: viewer, logIdx: 0, to: stablecoinDex, token: tokenA, value: 1_000n }),
+      // Destination token received back from the DEX.
+      transferRow({ from: stablecoinDex, logIdx: 1, to: viewer, token: tokenB, value: 990n }),
+      // Destination token forwarded to a third-party recipient in the same tx.
+      transferRow({ from: viewer, logIdx: 2, to: recipient, token: tokenB, value: 990n }),
+    ])
+    // The delivery leg folds into the swap, so there is no separate `swap`.
+    expect(items.some((item) => item.type === 'swap')).toBe(false)
+    const transfer = items.find((item) => item.type === 'transfer')
+    expect(transfer?.type).toBe('transfer')
+    if (transfer?.type !== 'transfer') return
+    expect(transfer.data.direction).toBe('out')
+    expect(transfer.data.sender).toBe(viewer)
+    expect(transfer.data.recipient).toBe(recipient)
+    expect(transfer.data.sourceToken).toEqual({ address: tokenA, amount: '1000' })
+    expect(transfer.data.destinationToken).toEqual({ address: tokenB, amount: '990' })
+  })
+
+  test('keeps a swap whose output stays with the swapper as a `swap`', async () => {
+    const tokenB = '0x5555555555555555555555555555555555555555' as Address.Address
+    const items = await classify([
+      transferRow({ from: viewer, logIdx: 0, to: stablecoinDex, token: tokenA, value: 1_000n }),
+      transferRow({ from: stablecoinDex, logIdx: 1, to: viewer, token: tokenB, value: 990n }),
+    ])
+    const swap = items.find((item) => item.type === 'swap')
+    expect(swap?.type).toBe('swap')
+    if (swap?.type !== 'swap') return
+    expect(swap.data.sourceToken).toEqual({ address: tokenA, amount: '1000' })
+    expect(swap.data.destinationToken).toEqual({ address: tokenB, amount: '990' })
+  })
+
+  test('classifies OrderCancelled as `order-cancelled`', async () => {
+    const items = await classify([
+      logRow({
+        address: stablecoinDex,
+        args: { orderId: 42n },
+        eventName: 'OrderCancelled',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('order-cancelled')
+    if (items[0]!.type !== 'order-cancelled') return
+    expect(items[0]!.data.orderId).toBe('42')
+  })
+
+  test('classifies FeesDistributed as `fees-distributed`', async () => {
+    const validator = '0xcccccccc00000000000000000000000000000000' as Address.Address
+    const items = await classify([
+      transferRow({ from: feeManager, logIdx: 0, to: validator, token: tokenA, value: 77n }),
+      logRow({
+        address: feeManager,
+        args: { amount: 77n, token: tokenA, validator },
+        eventName: 'FeesDistributed',
+        logIdx: 1,
+      }),
+    ])
+    expect(items[0]!.type).toBe('fees-distributed')
+    if (items[0]!.type !== 'fees-distributed') return
+    expect(items[0]!.data.sourceToken.amount).toBe('77')
+    expect(items[0]!.data.validator).toBe(validator)
+  })
+
+  test('classifies RebalanceSwap as `fee-rebalance-swap`', async () => {
+    const tokenB = '0x4444444444444444444444444444444444444444' as Address.Address
+    const items = await classify([
+      logRow({
+        address: feeManager,
+        args: {
+          amountIn: 10n,
+          amountOut: 9n,
+          swapper: viewer,
+          userToken: tokenB,
+          validatorToken: tokenA,
+        },
+        eventName: 'RebalanceSwap',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('fee-rebalance-swap')
+    if (items[0]!.type !== 'fee-rebalance-swap') return
+    expect(items[0]!.data.sourceToken.address).toBe(tokenA)
+    expect(items[0]!.data.destinationToken.address).toBe(tokenB)
+  })
+
+  test('classifies RewardDistributed as `reward-distributed` on the token contract', async () => {
+    const items = await classify([
+      transferRow({ from: viewer, logIdx: 0, to: tokenA, token: tokenA, value: 30n }),
+      logRow({
+        address: tokenA,
+        args: { amount: 30n, funder: viewer },
+        eventName: 'RewardDistributed',
+        logIdx: 1,
+      }),
+    ])
+    expect(items[0]!.type).toBe('reward-distributed')
+    if (items[0]!.type !== 'reward-distributed') return
+    expect(items[0]!.data.sourceToken.address).toBe(tokenA)
+    expect(items[0]!.data.sourceToken.amount).toBe('30')
+  })
+
+  test('classifies RewardRecipientSet as `reward-recipient-set`', async () => {
+    const recipient = '0x5555555555555555555555555555555555555555' as Address.Address
+    const items = await classify([
+      logRow({
+        address: tokenA,
+        args: { holder: viewer, recipient },
+        eventName: 'RewardRecipientSet',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('reward-recipient-set')
+    if (items[0]!.type !== 'reward-recipient-set') return
+    expect(items[0]!.data.recipient).toBe(recipient)
+  })
+
+  test('classifies SpendingLimitUpdated as `spending-limit-updated`', async () => {
+    const publicKey = '0x6666666666666666666666666666666666666666' as Address.Address
+    const items = await classify([
+      logRow({
+        address: accountKeychain,
+        args: { account: viewer, newLimit: 999n, publicKey, token: tokenA },
+        eventName: 'SpendingLimitUpdated',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('spending-limit-updated')
+    if (items[0]!.type !== 'spending-limit-updated') return
+    expect(items[0]!.data.publicKey).toBe(publicKey)
+    expect(items[0]!.data.sourceToken.amount).toBe('999')
+  })
+
+  test('classifies BurnBlocked as `burn-blocked` before plain burn', async () => {
+    const items = await classify([
+      transferRow({
+        from: viewer,
+        logIdx: 0,
+        to: '0x0000000000000000000000000000000000000000' as Address.Address,
+        token: tokenA,
+        value: 15n,
+      }),
+      logRow({
+        address: tokenA,
+        args: { amount: 15n, from: viewer },
+        eventName: 'BurnBlocked',
+        logIdx: 1,
+      }),
+    ])
+    expect(items[0]!.type).toBe('burn-blocked')
+    if (items[0]!.type !== 'burn-blocked') return
+    expect(items[0]!.data.sourceToken.amount).toBe('15')
+  })
+
+  test('classifies OrderFilled as `order-filled`', async () => {
+    const maker = '0x4444444444444444444444444444444444444444' as Address.Address
+    const items = await classify([
+      logRow({
+        address: stablecoinDex,
+        args: { amountFilled: 250n, maker, orderId: 7n, partialFill: true, taker: viewer },
+        eventName: 'OrderFilled',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('order-filled')
+    if (items[0]!.type !== 'order-filled') return
+    expect(items[0]!.data.orderId).toBe('7')
+    expect(items[0]!.data.amountFilled).toBe('250')
+    expect(items[0]!.data.partialFill).toBe(true)
+  })
+
+  test('classifies PairCreated as `pair-created`', async () => {
+    const quote = '0x5555555555555555555555555555555555555555' as Address.Address
+    const items = await classify([
+      logRow({
+        address: stablecoinDex,
+        args: { base: tokenA, key: `0x${'a'.repeat(64)}`, quote },
+        eventName: 'PairCreated',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('pair-created')
+    if (items[0]!.type !== 'pair-created') return
+    expect(items[0]!.data.base).toBe(tokenA)
+    expect(items[0]!.data.quote).toBe(quote)
+  })
+
+  test('classifies PauseStateUpdate as `token-pause-set`', async () => {
+    const items = await classify([
+      logRow({
+        address: tokenA,
+        args: { isPaused: true, updater: viewer },
+        eventName: 'PauseStateUpdate',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('token-pause-set')
+    if (items[0]!.type !== 'token-pause-set') return
+    expect(items[0]!.data.paused).toBe(true)
+    expect(items[0]!.data.updater).toBe(viewer)
+  })
+
+  test('classifies LogoURIUpdated as `token-logo-set`', async () => {
+    const items = await classify([
+      logRow({
+        address: tokenA,
+        args: { newLogoURI: 'https://example.com/logo.svg', updater: viewer },
+        eventName: 'LogoURIUpdated',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('token-logo-set')
+    if (items[0]!.type !== 'token-logo-set') return
+    expect(items[0]!.data.logoUri).toBe('https://example.com/logo.svg')
+  })
+
+  test('classifies RoleMembershipUpdated as `role-membership-set`', async () => {
+    const account = '0x6666666666666666666666666666666666666666' as Address.Address
+    const items = await classify([
+      logRow({
+        address: tokenA,
+        args: { account, hasRole: true, role: `0x${'1'.repeat(64)}`, sender: viewer },
+        eventName: 'RoleMembershipUpdated',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('role-membership-set')
+    if (items[0]!.type !== 'role-membership-set') return
+    expect(items[0]!.data.account).toBe(account)
+    expect(items[0]!.data.granted).toBe(true)
+  })
+
+  test('classifies TokenCreated before a co-located RoleMembershipUpdated', async () => {
+    const items = await classify([
+      logRow({
+        address: tokenA,
+        args: { account: viewer, hasRole: true, role: `0x${'1'.repeat(64)}`, sender: viewer },
+        eventName: 'RoleMembershipUpdated',
+        logIdx: 0,
+      }),
+      logRow({
+        address: tip20Factory,
+        args: {
+          admin: viewer,
+          currency: 'USD',
+          name: 'Test',
+          quoteToken: tokenA,
+          salt: `0x${'0'.repeat(64)}`,
+          symbol: 'TST',
+          token: tokenA,
+        },
+        eventName: 'TokenCreated',
+        logIdx: 1,
+      }),
+    ])
+    expect(items[0]!.type).toBe('token-created')
+  })
+
+  test('classifies PolicyCreated before the WhitelistUpdated it bundles', async () => {
+    const account = '0x7777777777777777777777777777777777777777' as Address.Address
+    const items = await classify([
+      logRow({
+        address: tokenA,
+        args: { account, allowed: true, policyId: 9n, updater: viewer },
+        eventName: 'WhitelistUpdated',
+        logIdx: 0,
+      }),
+      logRow({
+        address: tokenA,
+        args: { policyId: 9n, policyType: 1, updater: viewer },
+        eventName: 'PolicyCreated',
+        logIdx: 1,
+      }),
+    ])
+    expect(items[0]!.type).toBe('policy-created')
+    if (items[0]!.type !== 'policy-created') return
+    expect(items[0]!.data.policyId).toBe('9')
+    expect(items[0]!.data.policyType).toBe(1)
+  })
+
+  test('classifies WhitelistUpdated as `whitelist-updated`', async () => {
+    const account = '0x7777777777777777777777777777777777777777' as Address.Address
+    const items = await classify([
+      logRow({
+        address: tokenA,
+        args: { account, allowed: false, policyId: 9n, updater: viewer },
+        eventName: 'WhitelistUpdated',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('whitelist-updated')
+    if (items[0]!.type !== 'whitelist-updated') return
+    expect(items[0]!.data.allowed).toBe(false)
+  })
+
+  test('classifies MasterRegistered as `master-registered`', async () => {
+    const master = '0x8888888888888888888888888888888888888888' as Address.Address
+    const items = await classify([
+      logRow({
+        address: accountKeychain,
+        args: { masterAddress: master, masterId: '0xdeadbeef' },
+        eventName: 'MasterRegistered',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('master-registered')
+    if (items[0]!.type !== 'master-registered') return
+    expect(items[0]!.data.masterId).toBe('0xdeadbeef')
+    expect(items[0]!.data.masterAddress).toBe(master)
+  })
+
+  test('classifies NonceIncremented as `nonce-incremented`', async () => {
+    const items = await classify([
+      logRow({
+        address: accountKeychain,
+        args: { account: viewer, newNonce: 5n, nonceKey: 0n },
+        eventName: 'NonceIncremented',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('nonce-incremented')
+    if (items[0]!.type !== 'nonce-incremented') return
+    expect(items[0]!.data.nonce).toBe('5')
+  })
+
+  test('classifies ValidatorRotated before the ValidatorAdded it bundles', async () => {
+    const validator = '0x9999999999999999999999999999999999999999' as Address.Address
+    const feeRecipient = '0xabababababababababababababababababababab' as Address.Address
+    const items = await classify([
+      logRow({
+        address: accountKeychain,
+        args: {
+          egress: 'https://v.example.com:2',
+          feeRecipient,
+          index: 2n,
+          ingress: 'https://v.example.com:1',
+          publicKey: `0x${'2'.repeat(64)}`,
+          validatorAddress: validator,
+        },
+        eventName: 'ValidatorAdded',
+        logIdx: 0,
+      }),
+      logRow({
+        address: accountKeychain,
+        args: {
+          caller: viewer,
+          deactivatedIndex: 1n,
+          egress: 'https://v.example.com:2',
+          index: 2n,
+          ingress: 'https://v.example.com:1',
+          newPublicKey: `0x${'3'.repeat(64)}`,
+          oldPublicKey: `0x${'2'.repeat(64)}`,
+          validatorAddress: validator,
+        },
+        eventName: 'ValidatorRotated',
+        logIdx: 1,
+      }),
+    ])
+    expect(items[0]!.type).toBe('validator-rotated')
+    if (items[0]!.type !== 'validator-rotated') return
+    expect(items[0]!.data.index).toBe('2')
+    expect(items[0]!.data.deactivatedIndex).toBe('1')
+  })
+
+  test('classifies OwnershipTransferred as `ownership-transferred`', async () => {
+    const newOwner = '0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd' as Address.Address
+    const items = await classify([
+      logRow({
+        address: accountKeychain,
+        args: { newOwner, oldOwner: viewer },
+        eventName: 'OwnershipTransferred',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('ownership-transferred')
+    if (items[0]!.type !== 'ownership-transferred') return
+    expect(items[0]!.data.newOwner).toBe(newOwner)
+  })
+
+  test('classifies Initialized as `initialized`', async () => {
+    const items = await classify([
+      logRow({
+        address: accountKeychain,
+        args: { height: 42n },
+        eventName: 'Initialized',
+        logIdx: 0,
+      }),
+    ])
+    expect(items[0]!.type).toBe('initialized')
+    if (items[0]!.type !== 'initialized') return
+    expect(items[0]!.data.height).toBe('42')
+  })
+})