tapimo 0.0.0 → 0.0.2

package/dist/apps/activities.js

@@ -0,0 +1,3138 @@
+import { Hono } from 'hono';
+import { Address, Hex } from 'ox';
+import { parseEventLogs, zeroAddress } from 'viem';
+import { Abis, Addresses } from 'viem/tempo';
+import * as z from 'zod/mini';
+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 * 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 var schema;
+(function (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.
+     */
+    schema.Token = Transfers.schema.SourceToken;
+    /**
+     * A token transfer as classified by the feed: the `/transfers` row shape
+     * plus the feed-only, subject-relative fields (`direction`, `signer`) that
+     * the unscoped resource cannot carry, with `memo`/`attribution` always
+     * resolved (the feed already decodes the underlying events).
+     */
+    schema.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(schema.Token)
+            .check(z.describe('Token and amount delivered to the recipient when it differs from the source token — a cross-token transfer routed through the DEX. Omitted for a same-token transfer.')),
+        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: schema.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`). */
+    schema.items = [
+        z
+            .object({
+            ...base,
+            data: schema.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: schema.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: schema.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: schema.Token.check(z.describe('Token the address received in the swap.')),
+                signer: Signer,
+                sourceToken: schema.Token.check(z.describe('Token the address sent into the swap.')),
+            })
+                .check(z.describe('Swap inferred from token transfers through the DEX precompile. This feed entry is a summary, so per-fill details, route, and rate are not included.')),
+            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: schema.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(schema.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: schema.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: schema.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: schema.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: schema.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(schema.Token)
+                    .check(z.describe('Token and amount refunded to the payer on close, if any.')),
+                signer: Signer,
+                sourceToken: z
+                    .optional(schema.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: schema.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: schema.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: schema.Token.check(z.describe('Token and amount received from the fee AMM.')),
+                signer: Signer,
+                sourceToken: schema.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: schema.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: schema.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: schema.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' })),
+    ];
+    /** A single classified activity item. */
+    schema.Item = z
+        .union(schema.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. */
+    schema.Group = z
+        .object({
+        data: z
+            .object({
+            items: z.array(schema.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. */
+    schema.Entry = z
+        .union([...schema.items, schema.Group])
+        .check(z.describe('Either one activity item, or a grouped set of access-key activity items.'));
+    /** Schemas for the getAddressActivities operation. */
+    let getAddressActivities;
+    (function (getAddressActivities) {
+        /** Path parameters for address activity requests. */
+        getAddressActivities.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. */
+        getAddressActivities.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.
+         */
+        getAddressActivities.Response = z
+            .object({
+            data: z.array(schema.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.'));
+    })(getAddressActivities = schema.getAddressActivities || (schema.getAddressActivities = {}));
+    /** Schemas for the getTransactionActivities operation. */
+    let getTransactionActivities;
+    (function (getTransactionActivities) {
+        /** Path parameters for transaction activity requests. */
+        getTransactionActivities.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. */
+        getTransactionActivities.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`.
+         */
+        getTransactionActivities.Response = z
+            .object({
+            data: z.array(schema.Item).check(z.describe('Activity items classified from the transaction.')),
+        })
+            .check(z.describe('The human-readable activity that happened on a transaction.'));
+    })(getTransactionActivities = schema.getTransactionActivities || (schema.getTransactionActivities = {}));
+})(schema || (schema = {}));
+/**
+ * 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 = {
+    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) {
+    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 = {
+    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';
+/** 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'];
+/** Builds common public activity fields from the normalized transaction hash and representative log. */
+function baseFor(options) {
+    return {
+        perspective: options.perspective,
+        id: `${options.transactionHash}-${options.logIndex}`,
+        logIndex: options.logIndex,
+        timestamp: options.timestamp,
+        transactionHash: options.transactionHash,
+    };
+}
+/**
+ * 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().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({
+        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,
+                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().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({
+        // 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) {
+    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`,
+    });
+    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`,
+    });
+    const rows = 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',
+        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);
+    const group = groupByTx(rows)[0];
+    return classifyGroup(group, viewer, fingerprintMap, logs).map(withTitle);
+}
+/**
+ * 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, options) {
+    const { address, cursor, group = false, limit = 20, logs = false } = options;
+    const viewer = address.toLowerCase();
+    // 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 = cursor;
+    const allItems = [];
+    let hasMore = false;
+    let lastGroup;
+    // 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 = 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 };
+}
+/**
+ * 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) {
+    const { chainId, tidx: tidxClient } = deps;
+    function parseCursor(cursor) {
+        // 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], txIdx: decoded[1] };
+    }
+    /**
+     * 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) {
+        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}
+      `,
+        });
+        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',
+            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) {
+        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',
+            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) };
+        },
+    };
+}
+/**
+ * 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, q2, q3) {
+    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) {
+    const map = new Map();
+    const order = [];
+    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, viewer, fingerprintMap, includeLogs = false) {
+    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 = (txSender && Address.isEqual(txSender, viewer)) ||
+        (feePayer && Address.isEqual(feePayer, viewer))
+        ? 'outgoing'
+        : 'incoming';
+    const itemBase = (logIndex) => baseFor({ logIndex, perspective, timestamp, transactionHash: txHash });
+    const signer = 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))
+            return [{ ...base, data: { recipient: viewer, sourceToken }, type: 'mint' }];
+        if (Address.isEqual(to, zeroAddress))
+            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, ctx) {
+    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, ctx) {
+    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()
+        : null;
+    const signer = 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.to, viewer));
+        const refund = refundTransfer
+            ? token(refundTransfer.args.amount, refundTransfer.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();
+    for (const event of events) {
+        if (event.eventName === 'TransferWithMemo' && 'from' in event.args && 'to' in event.args) {
+            const args = event.args;
+            preferenceMap.set(`${args.from}:${args.to}:${args.amount}`, 'TransferWithMemo');
+        }
+        if (event.eventName === 'Mint' && 'amount' in event.args)
+            preferenceMap.set(`mint:${event.address}:${event.args.amount}`, 'Mint');
+        if (event.eventName === 'Burn' && 'amount' in event.args)
+            preferenceMap.set(`burn:${event.address}:${event.args.amount}`, 'Burn');
+    }
+    const dedupedEvents = events.filter((event) => {
+        if (event.eventName !== 'Transfer')
+            return true;
+        const args = event.args;
+        if (preferenceMap.has(`${args.from}:${args.to}:${args.amount}`))
+            return false;
+        if (Address.isEqual(args.from, zeroAddress) &&
+            preferenceMap.has(`mint:${event.address}:${args.amount}`))
+            return false;
+        if (Address.isEqual(args.to, zeroAddress) &&
+            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;
+        if (Address.isEqual(args.from, zeroAddress) &&
+            preferenceMap.has(`mint:${event.address}:${args.amount}`))
+            return false;
+        if (Address.isEqual(args.to, zeroAddress) &&
+            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.to, Addresses.stablecoinDex));
+    const fromDex = transfers.find((e) => Address.isEqual(e.args.from, Addresses.stablecoinDex));
+    if (toDex && fromDex) {
+        const swapper = fromDex.args.to;
+        const destTokenAddress = fromDex.address;
+        const sourceToken = token(toDex.args.amount, toDex.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.from, swapper) &&
+            !Address.isEqual(e.args.to, Addresses.stablecoinDex) &&
+            !Address.isEqual(e.args.to, swapper));
+        if (delivery) {
+            const args = delivery.args;
+            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),
+                    direction: Address.isEqual(args.to, viewer) ? 'in' : 'out',
+                    memo,
+                    recipient: args.to.toLowerCase(),
+                    sender: swapper.toLowerCase(),
+                    signer,
+                    sourceToken,
+                }),
+            ];
+        }
+        return [
+            {
+                ...itemBase(Math.min(logIndexOfEvent(toDex), logIndexOfEvent(fromDex))),
+                data: {
+                    destinationToken: token(fromDex.args.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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(mintEvent)),
+                data: {
+                    recipient: args.to.toLowerCase(),
+                    sourceToken: token(args.amount, mintEvent.address),
+                },
+                type: 'mint',
+            },
+        ];
+    }
+    const zeroTransferIn = transfers.find((e) => Address.isEqual(e.args.from, zeroAddress));
+    if (zeroTransferIn) {
+        const args = zeroTransferIn.args;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(zeroTransferIn)),
+                data: {
+                    recipient: args.to.toLowerCase(),
+                    sourceToken: token(args.amount, zeroTransferIn.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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(burnBlockedEvent)),
+                data: {
+                    sender: args.from.toLowerCase(),
+                    signer,
+                    sourceToken: token(args.amount, burnBlockedEvent.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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(burnEvent)),
+                data: {
+                    sender: args.from.toLowerCase(),
+                    signer,
+                    sourceToken: token(args.amount, burnEvent.address),
+                },
+                type: 'burn',
+            },
+        ];
+    }
+    const zeroTransferOut = transfers.find((e) => Address.isEqual(e.args.to, zeroAddress));
+    if (zeroTransferOut) {
+        const args = zeroTransferOut.args;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(zeroTransferOut)),
+                data: {
+                    sender: args.from.toLowerCase(),
+                    signer,
+                    sourceToken: token(args.amount, zeroTransferOut.address),
+                },
+                type: 'burn',
+            },
+        ];
+    }
+    // Approval (excluding zone-outbox spenders).
+    const approvalEvent = finalEvents.find((e) => e.eventName === 'Approval' &&
+        !Address.isEqual(e.args.spender, Addresses.zoneOutbox));
+    if (approvalEvent) {
+        const args = approvalEvent.args;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(approvalEvent)),
+                data: {
+                    signer,
+                    sourceToken: token(args.amount, approvalEvent.address),
+                    spender: args.spender.toLowerCase(),
+                },
+                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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(channelOpened)),
+                data: {
+                    channelId: args.channelId.toLowerCase(),
+                    payee: args.payee.toLowerCase(),
+                    payer: args.payer.toLowerCase(),
+                    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.to, tip20ChannelReserve));
+    const reserveOutflowTo = (recipient) => transfers.find((e) => Address.isEqual(e.args.from, tip20ChannelReserve) &&
+        Address.isEqual(e.args.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;
+        const tokenAddress = reserveInflow
+            ? reserveInflow.address
+            : zeroAddress;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(topUp)),
+                data: {
+                    channelId: args.channelId.toLowerCase(),
+                    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;
+        const payeeLeg = reserveOutflowTo(args.payee.toLowerCase());
+        const tokenAddress = payeeLeg
+            ? payeeLeg.address
+            : zeroAddress;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(settled)),
+                data: {
+                    channelId: args.channelId.toLowerCase(),
+                    payee: args.payee.toLowerCase(),
+                    payer: args.payer.toLowerCase(),
+                    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;
+        const payeeLeg = reserveOutflowTo(args.payee.toLowerCase());
+        const payerLeg = reserveOutflowTo(args.payer.toLowerCase());
+        return [
+            {
+                ...itemBase(logIndexOfEvent(channelClosed)),
+                data: {
+                    channelId: args.channelId.toLowerCase(),
+                    payee: args.payee.toLowerCase(),
+                    payer: args.payer.toLowerCase(),
+                    ...(payerLeg && args.refundedToPayer > 0n
+                        ? { refund: token(args.refundedToPayer, payerLeg.address) }
+                        : {}),
+                    signer,
+                    ...(payeeLeg
+                        ? { sourceToken: token(args.settledToPayee, payeeLeg.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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(closeCancelled)),
+                data: {
+                    channelId: args.channelId.toLowerCase(),
+                    payee: args.payee.toLowerCase(),
+                    payer: args.payer.toLowerCase(),
+                    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;
+        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;
+        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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(rebalanceSwap)),
+                data: {
+                    destinationToken: token(args.amountOut, args.userToken),
+                    signer,
+                    sourceToken: token(args.amountIn, args.validatorToken),
+                    swapper: args.swapper.toLowerCase(),
+                },
+                type: 'fee-rebalance-swap',
+            },
+        ];
+    }
+    // Validator fees distributed.
+    const feesDistributed = finalEvents.find((e) => e.eventName === 'FeesDistributed');
+    if (feesDistributed) {
+        const args = feesDistributed.args;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(feesDistributed)),
+                data: {
+                    signer,
+                    sourceToken: token(args.amount, args.token),
+                    validator: args.validator.toLowerCase(),
+                },
+                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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(rewardDistributed)),
+                data: {
+                    funder: args.funder.toLowerCase(),
+                    signer,
+                    sourceToken: token(args.amount, rewardDistributed.address),
+                },
+                type: 'reward-distributed',
+            },
+        ];
+    }
+    // Reward recipient redirected.
+    const rewardRecipientSet = finalEvents.find((e) => e.eventName === 'RewardRecipientSet');
+    if (rewardRecipientSet) {
+        const args = rewardRecipientSet.args;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(rewardRecipientSet)),
+                data: {
+                    holder: args.holder.toLowerCase(),
+                    recipient: args.recipient.toLowerCase(),
+                    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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(spendingLimitUpdated)),
+                data: {
+                    account: args.account.toLowerCase(),
+                    publicKey: args.publicKey.toLowerCase(),
+                    signer,
+                    sourceToken: token(args.newLimit, args.token),
+                },
+                type: 'spending-limit-updated',
+            },
+        ];
+    }
+    // Access-key lifecycle events — emitted alongside any co-located transfer.
+    const accessKeyItems = [];
+    for (const event of finalEvents) {
+        if (event.eventName === 'KeyAuthorized' &&
+            Address.isEqual(event.address, Addresses.accountKeychain)) {
+            const args = event.args;
+            accessKeyItems.push({
+                ...itemBase(logIndexOfEvent(event)),
+                data: {
+                    account: args.account.toLowerCase(),
+                    expiry: Number(args.expiry),
+                    publicKey: args.publicKey.toLowerCase(),
+                    signatureType: Number(args.signatureType),
+                },
+                type: 'access-key-created',
+            });
+        }
+        else if (event.eventName === 'KeyRevoked' &&
+            Address.isEqual(event.address, Addresses.accountKeychain)) {
+            const args = event.args;
+            accessKeyItems.push({
+                ...itemBase(logIndexOfEvent(event)),
+                data: {
+                    account: args.account.toLowerCase(),
+                    publicKey: args.publicKey.toLowerCase(),
+                },
+                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;
+        return [
+            {
+                ...itemBase(logIndexOfEvent(tokenCreated)),
+                data: {
+                    address: args.token.toLowerCase(),
+                    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) => value.toLowerCase();
+    const hx = (value) => value.toLowerCase();
+    const findEvent = (name) => 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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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.to, Addresses.feeManager));
+    if (userTransfers.length > 0) {
+        const t = userTransfers[0];
+        const args = t.args;
+        const to = args.to.toLowerCase();
+        const from = args.from.toLowerCase();
+        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);
+        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) {
+    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, blockNumber, data) {
+    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',
+    };
+}
+/**
+ * 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, data) {
+    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) {
+    const viemLogs = rows.map((r) => ({
+        address: r.logAddress,
+        blockHash: '0x0',
+        blockNumber: BigInt(r.blockNum),
+        data: (r.data ?? '0x'),
+        logIndex: r.logIdx,
+        removed: false,
+        topics: [r.selector, r.topic1, r.topic2, r.topic3].filter(Boolean),
+        transactionHash: r.txHash,
+        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, decoded) {
+    const decodedByIndex = new Map(decoded.map((event) => [event.logIndex, event]));
+    return rows
+        .map((row) => {
+        const base = {
+            address: row.logAddress,
+            data: (row.data ?? '0x'),
+            logIndex: row.logIdx,
+            topics: [row.selector, row.topic1, row.topic2, row.topic3].filter((topic) => topic !== null),
+        };
+        const event = decodedByIndex.get(row.logIdx);
+        if (!event)
+            return base;
+        return {
+            ...base,
+            args: (jsonSafe(event.args) ?? {}),
+            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) {
+    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 = {};
+        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) {
+    return (Value.toText(value)?.toLowerCase() ?? zeroAddress);
+}
+/** Lowercases a TIDX transaction hash column, defaulting to `0x` when absent. */
+function lowerHash(value) {
+    return (Value.toText(value)?.toLowerCase() ?? '0x');
+}
+/** Lowercases an optional TIDX address column, or null when absent. */
+function lowerOrNull(value) {
+    const text = Value.toText(value);
+    return text ? text.toLowerCase() : null;
+}
+/** Builds a stub token; `decimals`/`symbol` are filled by {@link enrichItem}. */
+function token(amount, address) {
+    return { address: address.toLowerCase(), amount: (amount ?? 0n).toString() };
+}
+/** Collects every token address referenced by an item's `data`. */
+function collectTokens(item, set) {
+    const data = item.data;
+    for (const key of tokenKeys) {
+        const t = data[key];
+        if (t)
+            set.add(t.address.toLowerCase());
+    }
+}
+/**
+ * Resolves metadata for every token referenced across a page of items and
+ * spreads it into each item's stub tokens, in place. Routes through the shared
+ * {@link Tokens.getTokenMetadata} (one `token.getMetadata` RPC per token,
+ * memoized under the `token:v1:…` key shared with `/tokens` and `/transfers`)
+ * instead of a parallel metadata fetch. Resolution is best-effort: a token
+ * whose metadata is unavailable keeps just `address`/`amount`.
+ */
+async function enrichTokens(c, options) {
+    const { chainId, items } = options;
+    const addresses = new Set();
+    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])
+        .catch(() => [address.toLowerCase(), undefined]))));
+    const byAddress = new Map(resolved);
+    for (const item of items)
+        enrichItem(item, byAddress);
+}
+/** Spreads resolved token metadata into an item's stub tokens, in place. */
+function enrichItem(item, byAddress) {
+    const data = item.data;
+    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) {
+    const entries = [];
+    let currentGroup = 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) {
+    return item.data.signer ?? 'self';
+}
+/** Unwraps single-item groups; otherwise wraps the items in a `group` entry. */
+function flushGroup(group) {
+    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, b) {
+    const da = new Date(a);
+    const db = new Date(b);
+    return (da.getUTCFullYear() === db.getUTCFullYear() &&
+        da.getUTCMonth() === db.getUTCMonth() &&
+        da.getUTCDate() === db.getUTCDate());
+}
+//# sourceMappingURL=activities.js.map