tapimo 0.0.0 → 0.0.2

package/src/apps/fee-amm.ts

@@ -0,0 +1,1121 @@
+import { Hono, type Context } from 'hono'
+import { AbiEvent, AbiParameters, Hash, type Hex, Value as core_Value } from 'ox'
+import { Abis, Addresses } from 'viem/tempo'
+import * as z from 'zod/mini'
+
+import type * as App from '../App.js'
+import * as Auth from '../internal/Auth.js'
+import * as Cache from '../internal/Cache.js'
+import * as Cursor from '../internal/Cursor.js'
+import * as 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 VerifiedTokens from '../internal/VerifiedTokens.js'
+import * as Tokens from './tokens.js'
+
+// The protocol Fee AMM lives at the reserved FeeManager address. Pools are
+// `(userToken, validatorToken)` pairs discovered from the `Mint` events the
+// FeeManager emits; there is no on-chain pool registry to enumerate.
+const feeManager = Addresses.feeManager.toLowerCase()
+
+// pathUSD is the protocol's default fee token: a transaction whose fee token
+// matches the validator's token (or falls back to pathUSD) pays fees without
+// needing a Fee AMM pool, so pathUSD is always fee-usable even when it has no
+// user-side pool. Lowercased to match the indexer's stored address casing.
+const pathUsd = Addresses.pathUsd.toLowerCase()
+
+// Topic0 hashes of the FeeManager `Mint` event, current and legacy. Both
+// signatures index `userToken` as topic2 and `validatorToken` as topic3, but
+// their other fields differ, so rows are decoded per selector: the current
+// event carries data words `[sender, amountValidatorToken, liquidity]` with
+// topic1 = `to`; the legacy event carries `[amountUserToken,
+// amountValidatorToken, liquidity]` with topic1 = `sender`. Queries hit the
+// raw `logs` table rather than a signature CTE: the event-CTE planner rejects
+// filters on event params, and the two signatures need different decoders
+// anyway.
+const mintTopic = AbiEvent.getSelector(
+  'event Mint(address sender, address indexed to, address indexed userToken, address indexed validatorToken, uint256 amountValidatorToken, uint256 liquidity)',
+)
+const legacyMintTopic = AbiEvent.getSelector(
+  'event Mint(address indexed sender, address indexed userToken, address indexed validatorToken, uint256 amountUserToken, uint256 amountValidatorToken, uint256 liquidity)',
+)
+
+/** Zod schemas owned by the fee AMM handlers. */
+export namespace schema {
+  /**
+   * A token referenced by a fee pool: its contract address plus best-effort
+   * metadata. Mirrors the transfer feed's `sourceToken` technique: `address`
+   * is always present; the metadata fields spread in only when resolution
+   * succeeds, so a token whose metadata is unavailable keeps just the bare
+   * reference. The pools listing extends this shape with the side's reserve
+   * (`getFeeAmmPools.Token`).
+   */
+  export const PoolToken = Schema.describe(
+    z.object({
+      address: Schema.TokenAddress.check(
+        z.describe('TIP-20 token contract address used by this fee pool.'),
+      ),
+      currency: z
+        .optional(z.string())
+        .check(
+          z.describe('Display currency for the token, when available.'),
+          z.meta({ examples: ['USD'] }),
+        ),
+      decimals: z
+        .optional(z.number().check(z.int(), z.nonnegative()))
+        .check(z.describe('Number of decimal places the token uses.'), z.meta({ examples: [6] })),
+      logoUri: z.optional(z.string()).check(
+        z.describe('URL for the token logo SVG, when available.'),
+        z.meta({
+          examples: [
+            'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
+          ],
+        }),
+      ),
+      name: z
+        .optional(z.string())
+        .check(z.describe('Human-readable token name.'), z.meta({ examples: ['USD Coin'] })),
+      symbol: z
+        .optional(z.string())
+        .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDC'] })),
+      verified: z
+        .optional(z.boolean())
+        .check(
+          z.describe('Whether Tempo has verified this token’s metadata.'),
+          z.meta({ examples: [true] }),
+        ),
+    }),
+    'A TIP-20 token used by a Fee AMM pool, with metadata when available.',
+  )
+
+  /** Schemas for the getFeeAmmPools operation. */
+  export namespace getFeeAmmPools {
+    /** Optional related resources that callers opt into via `include`. */
+    export const Include = z
+      .enum(['token'])
+      .check(z.describe('Optional related data you can request with `include`.'))
+
+    /**
+     * Parses a comma-separated `include` query value into a list of optional
+     * resources to embed. Token metadata resolution is one extra (batched)
+     * `token.getMetadata` round trip, so it runs only when `include=token` is
+     * requested; the base page returns each side's bare `address` plus its
+     * reserve and skips the lookup entirely.
+     */
+    export const includeQuery = Schema.includeQuery(
+      Include,
+      'Comma-separated related resources to include, such as `token` metadata.',
+    )
+
+    /** Query parameters for the fee pool list request. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        cursor: Schema.Cursor,
+        include: includeQuery,
+        limit: Schema.Limit,
+        page: Schema.Page,
+      })
+      .check(...Schema.pageChecks(), z.describe('Query parameters for listing Fee AMM pools.'))
+
+    /**
+     * One side of a fee pool: the token reference carrying the side's current
+     * on-chain reserve. `amount`/`formatted` come from `FeeManager.getPool`
+     * and are absent when the read fails (best-effort, like the metadata
+     * fields).
+     */
+    export const Token = Schema.describe(
+      z.extend(PoolToken, {
+        amount: z
+          .optional(Schema.DecimalString)
+          .check(
+            z.describe(
+              'Current onchain reserve for this token, in base units, from `FeeManager.getPool`. Omitted if the read fails.',
+            ),
+          ),
+        formatted: z
+          .optional(z.string())
+          .check(
+            z.describe(
+              'Reserve as a human-readable decimal string using the token’s `decimals`. Omitted if the read fails.',
+            ),
+            z.meta({ examples: ['1.5'] }),
+          ),
+      }),
+      'One token side of a Fee AMM pool, including its current onchain reserve when available.',
+    )
+
+    /** A fee AMM pool, aggregated from its `Mint` events. */
+    export const Pool = z
+      .object({
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('Timestamp when liquidity was first minted into this pool.'),
+            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+          ),
+        id: Schema.Hash.check(
+          z.describe('Stable resource id for the pool; this is the same value as `poolId`.'),
+        ),
+        lastMintAt: z.iso
+          .datetime()
+          .check(
+            z.describe('Timestamp when liquidity was most recently minted into this pool.'),
+            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+          ),
+        mintCount: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Number of liquidity mints into this pool.'),
+            z.meta({ examples: [25] }),
+          ),
+        poolId: Schema.Hash.check(
+          z.describe(
+            'Pool id computed as `keccak256(abi.encode(userToken, validatorToken))`, matching `FeeManager.getPoolId`.',
+          ),
+        ),
+        userToken: Token.check(
+          z.describe(
+            'Token users pay fees with in this pool, including its current reserve when available.',
+          ),
+        ),
+        validatorToken: Token.check(
+          z.describe(
+            'Token validators receive from this pool, including its current reserve when available.',
+          ),
+        ),
+      })
+      .check(z.describe('A Fee AMM pool discovered from its onchain `Mint` events.'))
+
+    /** Page of fee pools, ordered by mint count (most active first). */
+    export const Response = z
+      .object({
+        data: z
+          .array(Pool)
+          .check(z.describe('Fee AMM pools ordered by mint count, most active first.')),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of Fee AMM pools ordered by mint count, most active first.'))
+  }
+
+  /** Schemas for the getFeeAmmMints operation. */
+  export namespace getFeeAmmMints {
+    /** Query parameters for the pool mint list request. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        cursor: Schema.Cursor,
+        include: Schema.totalCountInclude,
+        limit: Schema.Limit,
+        order: Schema.Order,
+        page: Schema.Page,
+        userToken: z
+          .optional(Schema.TokenAddress)
+          .check(z.describe('Only include mints for pools where users paid fees with this token.')),
+        validatorToken: z
+          .optional(Schema.TokenAddress)
+          .check(z.describe('Only include mints for pools where validators receive this token.')),
+      })
+      .check(
+        ...Schema.pageChecks(),
+        z.describe('Query parameters for listing Fee AMM liquidity mints.'),
+      )
+
+    /** A single liquidity mint into a fee pool. */
+    export const Mint = z
+      .object({
+        amountUserToken: z
+          .optional(Schema.DecimalString)
+          .check(
+            z.describe(
+              'Amount of the user-side token deposited, in base units. Only present on legacy-signature mints.',
+            ),
+          ),
+        amountValidatorToken: Schema.DecimalString.check(
+          z.describe('Amount of the validator-side token deposited, in base units.'),
+        ),
+        blockNumber: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Block number where the mint occurred.'),
+            z.meta({ examples: [23456789] }),
+          ),
+        id: z.string().check(
+          z.describe(
+            'Stable mint id built from the transaction hash and log index (`${transactionHash}-${logIndex}`).',
+          ),
+          z.meta({
+            examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-0'],
+          }),
+        ),
+        liquidity: Schema.DecimalString.check(
+          z.describe('Amount of pool liquidity minted, as an integer string.'),
+        ),
+        logIndex: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Log index of this mint within the block.'),
+            z.meta({ examples: [0] }),
+          ),
+        minter: Schema.Address.check(z.describe('Address that deposited tokens into the pool.')),
+        recipient: z
+          .optional(Schema.Address)
+          .check(
+            z.describe(
+              'Address that received the minted liquidity. Only present on current-signature mints.',
+            ),
+          ),
+        timestamp: z.iso
+          .datetime()
+          .check(
+            z.describe('Block timestamp when the mint occurred.'),
+            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+          ),
+        transactionHash: Schema.Hash.check(
+          z.describe('Hash of the transaction that emitted this mint.'),
+        ),
+        userToken: PoolToken.check(z.describe('Token users pay fees with in this pool.')),
+        validatorToken: PoolToken.check(z.describe('Token validators receive from this pool.')),
+      })
+      .check(z.describe('One liquidity mint into a Fee AMM pool.'))
+
+    /** Page of fee pool mints, ordered by block then log index. */
+    export const Response = z
+      .object({
+        data: z.array(Mint).check(z.describe('Liquidity mints returned on this page.')),
+        meta: z
+          .optional(Schema.CountMeta)
+          .check(
+            z.describe('Response-wide metadata requested with `include`, such as `totalCount`.'),
+          ),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of Fee AMM liquidity mints.'))
+  }
+}
+
+/** Creates fee AMM handlers. */
+export function feeAmm() {
+  return new Hono<App.Environment>()
+    .get(
+      '/pools',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('query', schema.getFeeAmmPools.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Lists Fee AMM pools, most active first, so you can see which stablecoin fee conversions have the most liquidity activity.',
+        operationId: 'getFeeAmmPools',
+        responses: OpenApi.responses({
+          errors: { 502: 'The upstream Tempo indexer could not complete the request.' },
+          success: {
+            description: 'List of Fee AMM pools.',
+            schema: schema.getFeeAmmPools.Response,
+          },
+        }),
+        summary: 'List pools',
+        tags: ['Fee AMM'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.state,
+        name: 'tempo-api:fee-amm:v1',
+        key: (c) => Cache.urlKey(c, schema.getFeeAmmPools.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+
+        try {
+          const page = await listPools(c, {
+            chainId,
+            cursor: query.cursor,
+            limit: query.limit,
+            page: query.page,
+          })
+          const pools = page.data
+
+          // Reserves are one `getPool` eth_call per pool; viem auto-batches
+          // the concurrent calls into a single deployless multicall round
+          // trip (see `internal/Viem.ts`).
+          const reserves = await Timing.time(c, 'fee_amm_reserves', () =>
+            Promise.all(
+              pools.map((pool) =>
+                getPoolReserves(c, {
+                  chainId,
+                  userToken: pool.userToken,
+                  validatorToken: pool.validatorToken,
+                }),
+              ),
+            ),
+          )
+
+          // Token metadata is one extra (batched) `token.getMetadata` round
+          // trip, opt-in via `include=token`. Without it each side carries
+          // just its `address` and reserve; reserves still format via the
+          // `reserve` helper's TIP-20 (6-decimal) fallback.
+          const tokensByAddress = query.include.includes('token')
+            ? await resolveTokenMap(c, {
+                addresses: Array.from(
+                  new Set(pools.flatMap((pool) => [pool.userToken, pool.validatorToken])),
+                ),
+                chainId,
+              })
+            : undefined
+
+          const data = pools.map((pool, index) => {
+            const id = poolId(pool.userToken, pool.validatorToken)
+            const userToken = { address: pool.userToken, ...tokensByAddress?.get(pool.userToken) }
+            const validatorToken = {
+              address: pool.validatorToken,
+              ...tokensByAddress?.get(pool.validatorToken),
+            }
+            // Each side's reserve rides on its token reference (like the
+            // metadata fields): absent when the `getPool` read failed.
+            return {
+              createdAt: pool.createdAt,
+              id,
+              lastMintAt: pool.lastMintAt,
+              mintCount: pool.mintCount,
+              poolId: id,
+              userToken: {
+                ...userToken,
+                ...reserve(reserves[index]?.userToken, userToken.decimals),
+              },
+              validatorToken: {
+                ...validatorToken,
+                ...reserve(reserves[index]?.validatorToken, validatorToken.decimals),
+              },
+            }
+          })
+
+          return c.json(
+            Response.validated(schema.getFeeAmmPools.Response, {
+              data,
+              nextCursor: page.nextCursor,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/mints',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('query', schema.getFeeAmmMints.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description: 'Lists liquidity mints into Fee AMM pools.',
+        operationId: 'getFeeAmmMints',
+        responses: OpenApi.responses({
+          errors: { 502: 'The upstream Tempo indexer could not complete the request.' },
+          success: {
+            description: 'Page of Fee AMM liquidity mints.',
+            schema: schema.getFeeAmmMints.Response,
+          },
+        }),
+        summary: 'List mints',
+        tags: ['Fee AMM'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.feed,
+        name: 'tempo-api:fee-amm:v1',
+        key: (c) => Cache.urlKey(c, schema.getFeeAmmMints.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+
+        // A cursor page is anchored below the head, so its contents are
+        // append-only and effectively immutable; cache it aggressively. The
+        // head page (no cursor) keeps the route's short `feed` default.
+        if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+
+        try {
+          // `totalCount` is opt-in and shares the page's filters; run it
+          // concurrently with the page. Best-effort: a count failure omits
+          // `meta` rather than failing the page.
+          const countPromise = query.include.includes('totalCount')
+            ? countMints(c, {
+                chainId,
+                userToken: query.userToken,
+                validatorToken: query.validatorToken,
+              }).catch(() => undefined)
+            : undefined
+
+          const page = await listMints(c, {
+            chainId,
+            cursor: query.cursor,
+            limit: query.limit,
+            order: query.order,
+            page: query.page,
+            userToken: query.userToken,
+            validatorToken: query.validatorToken,
+          })
+
+          // Token references take the same enriched shape as the pools
+          // listing. The page's unique tokens are few (often one pool), and
+          // each resolution is memoized, so this stays one bounded fan-out.
+          const tokensByAddress = await resolveTokenMap(c, {
+            addresses: Array.from(
+              new Set(page.data.flatMap((mint) => [mint.userToken, mint.validatorToken])),
+            ),
+            chainId,
+          })
+          const data = page.data.map((mint) => ({
+            ...mint,
+            userToken: { address: mint.userToken, ...tokensByAddress.get(mint.userToken) },
+            validatorToken: {
+              address: mint.validatorToken,
+              ...tokensByAddress.get(mint.validatorToken),
+            },
+          }))
+
+          const meta = countPromise ? await countPromise : undefined
+          return c.json(
+            Response.validated(schema.getFeeAmmMints.Response, {
+              data,
+              ...(meta ? { meta } : {}),
+              nextCursor: page.nextCursor,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+/**
+ * Discovers fee pools by aggregating the FeeManager's `Mint` logs into one
+ * row per `(userToken, validatorToken)` pair, paginated and ordered by mint
+ * count (most active first), so the real fee pools (thousands to millions of
+ * mints) lead the head pages and the one-shot spam pairs (mint count 1) sink
+ * to the tail.
+ *
+ * Keyset pagination on `(mint_count, topic2, topic3)`: `mint_count` ranks the
+ * page (mutable — it grows as pools mint — so this is best-effort across mint
+ * activity, the inherent limit of a ranking feed), and the `(topic2, topic3)`
+ * group key is a stable, unique tiebreaker. A malformed cursor falls back to
+ * the head page.
+ */
+function listPools(c: Context<App.Environment>, options: listPools.Options) {
+  const { chainId, limit } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  const cursor = options.cursor
+    ? Cursor.decode(options.cursor, ['int', 'address', 'address'])
+    : undefined
+  // Bounded positional lane (exclusive with `cursor` at the schema): page 1 is
+  // the head page, so it shares the head's SQL and cache entries; deeper pages
+  // translate to a SQL OFFSET of `(page - 1) * limit` rows.
+  const offset =
+    options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : undefined
+
+  return Timing.time(c, 'fee_amm_pools', () =>
+    Store.memoize(
+      async () => {
+        // The keyset compares the aggregate `mint_count`, so it lives in the
+        // outer WHERE over the GROUP BY subquery. Topics are padded 32-byte
+        // log topics, so render their literals via `padTopic` (lowercased to
+        // match ClickHouse's stored topic casing) rather than `Cursor.literal`.
+        const keyset =
+          cursor !== undefined
+            ? ` WHERE ${Cursor.keyset([
+                { literal: Cursor.literal(cursor[0]!, 'int'), name: 'mint_count', order: 'desc' },
+                {
+                  literal: `'${padTopic(cursor[1] as z.output<typeof Schema.Address>).toLowerCase()}'`,
+                  name: 'topic2',
+                  order: 'desc',
+                },
+                {
+                  literal: `'${padTopic(cursor[2] as z.output<typeof Schema.Address>).toLowerCase()}'`,
+                  name: 'topic3',
+                  order: 'desc',
+                },
+              ])}`
+            : ''
+
+        // Raw-`logs` ClickHouse aggregate (dynamic query, hence the cast):
+        // ordering is by mint count so the head pages surface the real fee
+        // pools and the one-shot spam pairs sink to the tail. Fetch one extra
+        // row to detect `hasMore` without a separate count query.
+        const result = await tidx.fetch({
+          chainId,
+          engine: 'clickhouse',
+          query: `
+            SELECT topic2, topic3, mint_count, first_at, last_at
+            FROM (
+              SELECT topic2, topic3, count() AS mint_count, min(block_timestamp) AS first_at, max(block_timestamp) AS last_at
+              FROM logs
+              WHERE address = '${feeManager}' AND selector IN ('${mintTopic}', '${legacyMintTopic}')
+              GROUP BY topic2, topic3
+            )${keyset}
+            ORDER BY mint_count DESC, topic2 DESC, topic3 DESC
+            LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+          ` as string,
+        })
+
+        // The next page anchors below the last row's `(mint_count, topic2,
+        // topic3)`; topics use the lowercase unpadded address so they round
+        // trip through the keyset literals above.
+        const page = Cursor.paginate({
+          rows: result.rows,
+          limit,
+          key: (row) => {
+            const mintCount = Value.toNumber(row['mint_count'])
+            const userToken = unpadTopic(Value.toText(row['topic2']))?.toLowerCase()
+            const validatorToken = unpadTopic(Value.toText(row['topic3']))?.toLowerCase()
+            return mintCount !== undefined &&
+              userToken !== undefined &&
+              validatorToken !== undefined
+              ? [mintCount, userToken, validatorToken]
+              : undefined
+          },
+        })
+
+        const data: listPools.Pool[] = []
+        for (const row of page.rows) {
+          const userToken = Schema.Address.safeParse(unpadTopic(Value.toText(row['topic2'])))
+          const validatorToken = Schema.Address.safeParse(unpadTopic(Value.toText(row['topic3'])))
+          const mintCount = Value.toNumber(row['mint_count'])
+          const createdAt = Value.toIsoDateTime(row['first_at'])
+          const lastMintAt = Value.toIsoDateTime(row['last_at'])
+          if (
+            !userToken.success ||
+            !validatorToken.success ||
+            mintCount === undefined ||
+            createdAt === undefined ||
+            lastMintAt === undefined
+          )
+            continue
+          data.push({
+            createdAt,
+            lastMintAt,
+            mintCount,
+            userToken: userToken.data,
+            validatorToken: validatorToken.data,
+          })
+        }
+
+        return { data, nextCursor: page.nextCursor }
+      },
+      {
+        key: `feeamm:v1:${chainId}:pools:${cursor ? `cursor:${cursor[0]}:${cursor[1]}:${cursor[2]}` : offset !== undefined ? `page:${options.page}` : 'head'}:${limit}`,
+        store,
+        ttl: Ttl.minutes(1),
+      },
+    ),
+  )
+}
+
+declare namespace listPools {
+  /** Options for {@link listPools}. */
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    /** Opaque keyset cursor anchoring the page; omit for the head page. */
+    cursor?: string | undefined
+    limit: number
+    /** 1-indexed page number (positional pagination; exclusive with `cursor`). */
+    page?: number | undefined
+  }
+  /** A discovered pool, aggregated from its `Mint` logs. */
+  type Pool = {
+    /** ISO timestamp of the pool's first mint. */
+    createdAt: string
+    /** ISO timestamp of the pool's most recent mint. */
+    lastMintAt: string
+    mintCount: number
+    userToken: z.output<typeof Schema.Address>
+    validatorToken: z.output<typeof Schema.Address>
+  }
+}
+
+/**
+ * The set of token addresses usable to pay transaction fees on a chain: the
+ * curated verified tokens that have at least one Fee AMM pool (i.e. appear as a
+ * `userToken` / topic2 in the FeeManager's `Mint` logs), plus the protocol
+ * default fee token (`pathUSD`), which pays fees without needing a pool.
+ * Addresses are lowercased to match the indexer's stored casing.
+ *
+ * The set is intentionally gated to the verified list rather than every pooled
+ * token: anyone can mint a one-shot spam pool, so the raw set of pool
+ * `userToken`s is unbounded (tens of thousands on busy chains) and those
+ * liquidity-less pools can't actually settle fees. Restricting to verified
+ * tokens keeps the set small (a handful of USD stablecoins), bounds the scan
+ * (the `topic2 IN (…)` candidate list is the verified list), and matches the
+ * tokens fees are realistically paid in.
+ *
+ * Memoized per chain and verified-snapshot version (the only inputs), so
+ * callers — e.g. the address balances endpoint — can flag which holdings are
+ * fee-usable without a second `/fee-amm/pools` query.
+ */
+export async function feeTokenSet(
+  c: Context<App.Environment>,
+  chainId: z.output<typeof Schema.ChainId>,
+): Promise<Set<string>> {
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  const snapshot = await VerifiedTokens.snapshot(c, chainId)
+  // pathUSD is always fee-usable; the verified tokens are the only other
+  // candidates we probe for a pool. With no verified candidates there is
+  // nothing to query — pathUSD stands alone.
+  const candidates = snapshot.list.map((token) => token.address.toLowerCase())
+  if (candidates.length === 0) return new Set([pathUsd])
+
+  // `memoize` JSON-encodes its value, so cache a plain `string[]` and rebuild
+  // the `Set` per call (cheap; the list is a handful of stablecoins).
+  const addresses = await Timing.time(c, 'fee_token_set', () =>
+    Store.memoize(
+      async () => {
+        // Dynamic raw-`logs` query (hence the cast), mirroring the pools
+        // listing's FeeManager `Mint` filter but collapsing to the distinct
+        // user-side tokens — and scoped to the verified candidates via
+        // `topic2 IN (…)` so the result is bounded by the verified list.
+        const topics = candidates.map((address) => `'${padTopic(address as `0x${string}`)}'`)
+        const result = await tidx.fetch({
+          chainId,
+          engine: 'clickhouse',
+          query: `
+            SELECT DISTINCT topic2
+            FROM logs
+            WHERE address = '${feeManager}' AND selector IN ('${mintTopic}', '${legacyMintTopic}')
+              AND topic2 IN (${topics.join(', ')})
+          ` as string,
+        })
+        const tokens = new Set<string>([pathUsd])
+        for (const row of result.rows) {
+          const token = unpadTopic(Value.toText(row['topic2']))?.toLowerCase()
+          if (token !== undefined && Schema.Address.safeParse(token).success) tokens.add(token)
+        }
+        return Array.from(tokens)
+      },
+      {
+        key: `feeamm:v2:${chainId}:fee-token-set:v:${snapshot.version}`,
+        store,
+        ttl: Ttl.minutes(5),
+      },
+    ),
+  )
+  return new Set(addresses)
+}
+
+/**
+ * Reads a pool's current on-chain reserves via `FeeManager.getPool`, memoized
+ * briefly per pool. Reserves are best-effort decoration on the pool listing:
+ * a failing RPC read resolves to `null` (degrading that pool's reserve
+ * fields) rather than failing the whole response. Failures are not memoized,
+ * so the next request retries.
+ */
+function getPoolReserves(
+  c: Context<App.Environment>,
+  options: getPoolReserves.Options,
+): Promise<getPoolReserves.Reserves | null> {
+  const { chainId, userToken, validatorToken } = options
+  const client = c.get('getClient')(chainId)
+  const store = c.get('store')
+
+  return Store.memoize(
+    async () => {
+      const pool = await client.readContract({
+        abi: Abis.feeAmm,
+        address: Addresses.feeManager,
+        args: [userToken, validatorToken],
+        functionName: 'getPool',
+      })
+      return {
+        userToken: pool.reserveUserToken.toString(),
+        validatorToken: pool.reserveValidatorToken.toString(),
+      }
+    },
+    {
+      key: `feeamm:v1:${chainId}:pool:${userToken}:${validatorToken}:reserves`,
+      store,
+      ttl: Ttl.seconds(30),
+    },
+  ).catch(() => null)
+}
+
+declare namespace getPoolReserves {
+  /** Options for {@link getPoolReserves}. */
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    userToken: z.output<typeof Schema.Address>
+    validatorToken: z.output<typeof Schema.Address>
+  }
+  /** Raw base-unit reserves of both pool sides. */
+  type Reserves = {
+    /** User-side token reserve in its base unit. */
+    userToken: string
+    /** Validator-side token reserve in its base unit. */
+    validatorToken: string
+  }
+}
+
+/**
+ * Lists `Mint` logs as a keyset-paginated page on `(block_num, log_idx)`,
+ * optionally filtered by the pool's tokens. Runs on ClickHouse: the postgres
+ * `logs` table has no topic index, so topic-filtered pages exceed its
+ * statement timeout, while ClickHouse serves every filter shape.
+ */
+function listMints(c: Context<App.Environment>, options: listMints.Options) {
+  const { chainId, limit, order, userToken, validatorToken } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  const direction = order === 'asc' ? 'ASC' : 'DESC'
+  // Keyset pagination: anchor the page below the previous row's
+  // `(block, log_idx)` position instead of a numeric offset, so rows arriving
+  // at the head can't shift items across pages. A malformed cursor falls back
+  // to the head page.
+  const cursor = options.cursor ? Cursor.decode(options.cursor, ['int', 'int']) : undefined
+  // Bounded positional lane (exclusive with `cursor` at the schema): page 1 is
+  // the head page, so it shares the head's SQL and cache entries; deeper pages
+  // translate to a SQL OFFSET of `(page - 1) * limit` rows.
+  const offset =
+    options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : undefined
+
+  return Timing.time(c, 'fee_amm_mints', () =>
+    Store.memoize(
+      async () => {
+        const filters = [
+          `address = '${feeManager}'`,
+          `selector IN ('${mintTopic}', '${legacyMintTopic}')`,
+        ]
+        if (userToken !== undefined) filters.push(`topic2 = '${padTopic(userToken)}'`)
+        if (validatorToken !== undefined) filters.push(`topic3 = '${padTopic(validatorToken)}'`)
+        if (cursor !== undefined)
+          filters.push(
+            Cursor.keyset([
+              { literal: Cursor.literal(cursor[0]!, 'int'), name: 'block_num', order },
+              { literal: Cursor.literal(cursor[1]!, 'int'), name: 'log_idx', order },
+            ]),
+          )
+
+        // Fetch one extra row to detect `hasMore` without a separate count
+        // query. Raw-`logs` dynamic query, hence the cast. `block_timestamp`
+        // is aliased to a non-standard name on purpose: the TIDX client
+        // coerces standard `logs` columns, and its coercion parses
+        // ClickHouse's timezone-less `DateTime` text as *local* time. The
+        // alias passes the raw text through so `Value.toIsoDateTime` can
+        // apply its UTC normalization instead.
+        const result = await tidx.fetch({
+          chainId,
+          engine: 'clickhouse',
+          query: `
+            SELECT tx_hash, block_num, log_idx, block_timestamp AS block_time, selector, topic1, topic2, topic3, data
+            FROM logs
+            WHERE ${filters.join(' AND ')}
+            ORDER BY block_num ${direction}, log_idx ${direction}
+            LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+          ` as string,
+        })
+
+        // The next page anchors below the last fetched row's `(block, log_idx)`.
+        const page = Cursor.paginate({
+          rows: result.rows,
+          limit,
+          key: (row) => {
+            const block = Value.toNumber(row['block_num'])
+            const index = Value.toNumber(row['log_idx'])
+            return block !== undefined && index !== undefined ? [block, index] : undefined
+          },
+        })
+
+        const data: decodeMint.Mint[] = []
+        for (const row of page.rows) {
+          const mint = decodeMint(row)
+          if (mint) data.push(mint)
+        }
+        return { data, nextCursor: page.nextCursor }
+      },
+      {
+        key: `feeamm:v1:${chainId}:mints:${order}:${userToken ?? ''}:${validatorToken ?? ''}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : offset !== undefined ? `page:${options.page}` : 'head'}:${limit}`,
+        store,
+        ttl: Ttl.seconds(15),
+      },
+    ),
+  )
+}
+
+declare namespace listMints {
+  /** Options for {@link listMints}. */
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    /** Opaque keyset cursor anchoring the page; omit for the head page. */
+    cursor?: string | undefined
+    limit: number
+    /** 1-indexed page number (positional pagination; exclusive with `cursor`). */
+    page?: number | undefined
+    order: 'asc' | 'desc'
+    /** Restrict to pools with this user-side token. */
+    userToken?: z.output<typeof Schema.Address> | undefined
+    /** Restrict to pools with this validator-side token. */
+    validatorToken?: z.output<typeof Schema.Address> | undefined
+  }
+}
+
+/**
+ * Exact total count of pool mints matching the same filters as the page. Runs
+ * on ClickHouse over `logs`, pruning on the FeeManager `address` (the page's
+ * own engine/key). Because `address` aligns with the `logs` sort key,
+ * ClickHouse counts via the sparse primary index without a row scan, so the
+ * count is exact and cheap with no cap (`totalCountCapped` is always `false`) —
+ * verified at ~20M matching mints in ~1s.
+ */
+function countMints(
+  c: Context<App.Environment>,
+  options: countMints.Options,
+): Promise<z.output<typeof Schema.CountMeta>> {
+  const { chainId, userToken, validatorToken } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  return Timing.time(c, 'fee_amm_mints_count', () =>
+    Store.memoize(
+      async () => {
+        const filters = [
+          `address = '${feeManager}'`,
+          `selector IN ('${mintTopic}', '${legacyMintTopic}')`,
+        ]
+        if (userToken !== undefined) filters.push(`topic2 = '${padTopic(userToken)}'`)
+        if (validatorToken !== undefined) filters.push(`topic3 = '${padTopic(validatorToken)}'`)
+        const result = await tidx.fetch({
+          chainId,
+          engine: 'clickhouse',
+          query: `SELECT count(*) AS total FROM logs WHERE ${filters.join(' AND ')}` as string,
+        })
+        const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0
+        return { totalCountCapped: false, totalCount }
+      },
+      {
+        key: `feeamm:v1:${chainId}:mints-count:${userToken ?? ''}:${validatorToken ?? ''}`,
+        store,
+        ttl: Ttl.seconds(15),
+      },
+    ),
+  )
+}
+
+declare namespace countMints {
+  /** Filters for {@link countMints}: the page filters minus pagination. */
+  type Options = Pick<listMints.Options, 'chainId' | 'userToken' | 'validatorToken'>
+}
+
+/**
+ * Decodes one raw `Mint` log row, dispatching on its selector (current vs
+ * legacy signature — see the topic constants for the field layouts). Returns
+ * undefined for rows that fail to decode so callers can skip them.
+ */
+function decodeMint(row: Record<string, unknown>): decodeMint.Mint | undefined {
+  const selector = Value.toText(row['selector'])
+  const transactionHash = Schema.Hash.safeParse(row['tx_hash'])
+  const blockNumber = Value.toNumber(row['block_num'])
+  const logIndex = Value.toNumber(row['log_idx'])
+  const timestamp = Value.toIsoDateTime(row['block_time'])
+  const userToken = Schema.Address.safeParse(unpadTopic(Value.toText(row['topic2'])))
+  const validatorToken = Schema.Address.safeParse(unpadTopic(Value.toText(row['topic3'])))
+  const data = Value.toText(row['data'])
+  if (
+    !transactionHash.success ||
+    blockNumber === undefined ||
+    logIndex === undefined ||
+    timestamp === undefined ||
+    !userToken.success ||
+    !validatorToken.success ||
+    data === undefined
+  )
+    return undefined
+
+  const word = (index: number) => data.slice(2 + 64 * index, 2 + 64 * (index + 1))
+  const uint = (value: string) =>
+    /^[0-9a-fA-F]{64}$/.test(value) ? BigInt(`0x${value}`).toString() : undefined
+
+  if (selector === mintTopic) {
+    const minter = Schema.Address.safeParse(`0x${word(0).slice(24)}`)
+    const recipient = Schema.Address.safeParse(unpadTopic(Value.toText(row['topic1'])))
+    const amountValidatorToken = uint(word(1))
+    const liquidity = uint(word(2))
+    if (
+      !minter.success ||
+      !recipient.success ||
+      amountValidatorToken === undefined ||
+      liquidity === undefined
+    )
+      return undefined
+    return {
+      amountValidatorToken,
+      blockNumber,
+      id: `${transactionHash.data}-${logIndex}`,
+      liquidity,
+      logIndex,
+      minter: minter.data,
+      recipient: recipient.data,
+      timestamp,
+      transactionHash: transactionHash.data,
+      userToken: userToken.data,
+      validatorToken: validatorToken.data,
+    }
+  }
+
+  if (selector === legacyMintTopic) {
+    const minter = Schema.Address.safeParse(unpadTopic(Value.toText(row['topic1'])))
+    const amountUserToken = uint(word(0))
+    const amountValidatorToken = uint(word(1))
+    const liquidity = uint(word(2))
+    if (
+      !minter.success ||
+      amountUserToken === undefined ||
+      amountValidatorToken === undefined ||
+      liquidity === undefined
+    )
+      return undefined
+    return {
+      amountUserToken,
+      amountValidatorToken,
+      blockNumber,
+      id: `${transactionHash.data}-${logIndex}`,
+      liquidity,
+      logIndex,
+      minter: minter.data,
+      timestamp,
+      transactionHash: transactionHash.data,
+      userToken: userToken.data,
+      validatorToken: validatorToken.data,
+    }
+  }
+
+  return undefined
+}
+
+declare namespace decodeMint {
+  /**
+   * A decoded `Mint` row, carrying bare token addresses. The route shapes
+   * them into the enriched `PoolToken` references before responding.
+   */
+  type Mint = Omit<z.output<typeof schema.getFeeAmmMints.Mint>, 'userToken' | 'validatorToken'> & {
+    /** The pool's user-side (fee) token address. */
+    userToken: z.output<typeof Schema.Address>
+    /** The pool's validator-side token address. */
+    validatorToken: z.output<typeof Schema.Address>
+  }
+}
+
+/**
+ * Resolves best-effort metadata for the given token addresses, sharing one
+ * verified-token snapshot across the lookups. Mirrors the transfer feed's
+ * `sourceToken` enrichment: a token whose metadata is unavailable maps to
+ * undefined, so call sites spreading the result keep just the bare `address`
+ * (the `PoolToken` shape).
+ *
+ * Unlike the full token resource, this resolves only the on-chain metadata
+ * (one `token.getMetadata` read per token, auto-batched into a single
+ * multicall) plus the in-memory verified snapshot. It deliberately skips the
+ * curated R2 logo lookup (`getTokenLogo`), which is an un-batched storage read
+ * per token and the dominant cost of the pools/mints listings; `logoUri`
+ * therefore falls back to the verified entry's curated URL or the precompile's
+ * on-chain `logoURI`, both already in hand.
+ */
+async function resolveTokenMap(c: Context<App.Environment>, options: resolveTokenMap.Options) {
+  const { addresses, chainId } = options
+  const snapshot = await VerifiedTokens.snapshot(c, chainId)
+  const resolved = await Timing.time(c, 'tokens', () =>
+    Promise.all(
+      addresses.map((token) =>
+        Tokens.getTokenMetadata(c, { address: token, chainId })
+          .then((metadata) => {
+            const verified = snapshot.byAddress.get(token)
+            return [
+              token,
+              {
+                currency: metadata.currency,
+                decimals: metadata.decimals,
+                logoUri: verified?.logoUri ?? metadata.logoUri,
+                name: metadata.name,
+                symbol: metadata.symbol,
+                verified: snapshot.byAddress.has(token),
+              },
+            ] as const
+          })
+          .catch(() => [token, undefined] as const),
+      ),
+    ),
+  )
+  return new Map(resolved)
+}
+
+declare namespace resolveTokenMap {
+  /** Options for {@link resolveTokenMap}. */
+  type Options = {
+    /** Unique token addresses to resolve. */
+    addresses: readonly z.output<typeof Schema.Address>[]
+    /** Tempo chain id. */
+    chainId: z.output<typeof Schema.ChainId>
+  }
+}
+
+/**
+ * Computes a pool id locally: `keccak256(abi.encode(userToken,
+ * validatorToken))`, matching the on-chain `FeeManager.getPoolId`.
+ */
+function poolId(
+  userToken: z.output<typeof Schema.Address>,
+  validatorToken: z.output<typeof Schema.Address>,
+): Hex.Hex {
+  return Hash.keccak256(
+    AbiParameters.encode(AbiParameters.from(['address', 'address']), [userToken, validatorToken]),
+  )
+}
+
+/**
+ * Shapes one side's on-chain reserve for spreading into its token reference:
+ * the base-unit `amount` plus its `formatted` decimal form. `decimals` comes
+ * from the side's resolved token metadata; an unresolvable token falls back
+ * to 6, the fixed TIP-20 precision, so the reserve still formats. A missing
+ * amount (failed `getPool` read) yields undefined, leaving both fields absent.
+ */
+function reserve(
+  amount: string | undefined,
+  decimals: number | undefined,
+): { amount: string; formatted: string } | undefined {
+  if (amount === undefined) return undefined
+  return { amount, formatted: core_Value.format(BigInt(amount), decimals ?? 6) }
+}
+
+/** Left-pads a 20-byte address to its 32-byte log-topic form. */
+function padTopic(address: z.output<typeof Schema.Address>): string {
+  return `0x${'0'.repeat(24)}${address.slice(2)}`
+}
+
+/** Unpads a 32-byte log topic to its trailing 20-byte address. */
+function unpadTopic(topic: string | undefined): string | undefined {
+  return topic === undefined ? undefined : `0x${topic.slice(26)}`
+}