tapimo 0.0.0 → 0.0.2

package/dist/apps/fee-amm.js

@@ -0,0 +1,815 @@
+import { Hono } from 'hono';
+import { AbiEvent, AbiParameters, Hash, Value as core_Value } from 'ox';
+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 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 var schema;
+(function (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`).
+     */
+    schema.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. */
+    let getFeeAmmPools;
+    (function (getFeeAmmPools) {
+        /** Optional related resources that callers opt into via `include`. */
+        getFeeAmmPools.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.
+         */
+        getFeeAmmPools.includeQuery = Schema.includeQuery(getFeeAmmPools.Include, 'Comma-separated related resources to include, such as `token` metadata.');
+        /** Query parameters for the fee pool list request. */
+        getFeeAmmPools.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            cursor: Schema.Cursor,
+            include: getFeeAmmPools.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).
+         */
+        getFeeAmmPools.Token = Schema.describe(z.extend(schema.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. */
+        getFeeAmmPools.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: getFeeAmmPools.Token.check(z.describe('Token users pay fees with in this pool, including its current reserve when available.')),
+            validatorToken: getFeeAmmPools.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). */
+        getFeeAmmPools.Response = z
+            .object({
+            data: z
+                .array(getFeeAmmPools.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.'));
+    })(getFeeAmmPools = schema.getFeeAmmPools || (schema.getFeeAmmPools = {}));
+    /** Schemas for the getFeeAmmMints operation. */
+    let getFeeAmmMints;
+    (function (getFeeAmmMints) {
+        /** Query parameters for the pool mint list request. */
+        getFeeAmmMints.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. */
+        getFeeAmmMints.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: schema.PoolToken.check(z.describe('Token users pay fees with in this pool.')),
+            validatorToken: schema.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. */
+        getFeeAmmMints.Response = z
+            .object({
+            data: z.array(getFeeAmmMints.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.'));
+    })(getFeeAmmMints = schema.getFeeAmmMints || (schema.getFeeAmmMints = {}));
+})(schema || (schema = {}));
+/** Creates fee AMM handlers. */
+export function feeAmm() {
+    return new Hono()
+        .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({
+        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({
+        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, 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]).toLowerCase()}'`,
+                    name: 'topic2',
+                    order: 'desc',
+                },
+                {
+                    literal: `'${padTopic(cursor[2]).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}` : ''}
+          `,
+        });
+        // 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 = [];
+        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),
+    }));
+}
+/**
+ * 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, chainId) {
+    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)}'`);
+        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(', ')})
+          `,
+        });
+        const tokens = new Set([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, options) {
+    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);
+}
+/**
+ * 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, 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}` : ''}
+          `,
+        });
+        // 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 = [];
+        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),
+    }));
+}
+/**
+ * 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, options) {
+    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 ')}`,
+        });
+        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),
+    }));
+}
+/**
+ * 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) {
+    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) => data.slice(2 + 64 * index, 2 + 64 * (index + 1));
+    const uint = (value) => /^[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;
+}
+/**
+ * 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, 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),
+            },
+        ];
+    })
+        .catch(() => [token, undefined]))));
+    return new Map(resolved);
+}
+/**
+ * Computes a pool id locally: `keccak256(abi.encode(userToken,
+ * validatorToken))`, matching the on-chain `FeeManager.getPoolId`.
+ */
+function poolId(userToken, validatorToken) {
+    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, decimals) {
+    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) {
+    return `0x${'0'.repeat(24)}${address.slice(2)}`;
+}
+/** Unpads a 32-byte log topic to its trailing 20-byte address. */
+function unpadTopic(topic) {
+    return topic === undefined ? undefined : `0x${topic.slice(26)}`;
+}
+//# sourceMappingURL=fee-amm.js.map