tapimo 0.0.0 → 0.0.2

package/src/apps/balances.ts

@@ -0,0 +1,533 @@
+import { Hono, type Context } from 'hono'
+import { Hex, Value as core_Value } from 'ox'
+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 Timing from '../internal/Timing.js'
+import * as Value from '../internal/Value.js'
+import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import * as FeeAmm from './fee-amm.js'
+import * as Tokens from './tokens.js'
+
+// TIP-20 tokens are minted by the TIP-20 factory and live at deterministic
+// `0x20c0…`-prefixed addresses (e.g. pathUSD `0x20c0…0000`). The indexer's
+// `token_balances_snapshot` view, by contrast, records balances for every
+// Transfer-emitting contract, so balance queries filter on this prefix to keep
+// non-TIP-20 tokens (which have no resolvable TIP-20 metadata) out of results.
+const tip20AddressPrefix = '0x20c0'
+
+/** Zod schemas owned by the balance handlers. */
+export namespace schema {
+  /** Schemas for the getAddressBalances operation. */
+  export namespace getAddressBalances {
+    /** Path parameters for address balance requests. */
+    export const Params = z
+      .object({
+        address: Schema.Address.check(
+          z.describe('The account address whose token balances you want to list.'),
+        ),
+      })
+      .check(z.describe('Path parameters for listing an account’s token balances.'))
+
+    /** Query parameters for address balance requests. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        currency: z
+          .optional(z.string())
+          .check(
+            z.meta({ examples: VerifiedTokens.currencies }),
+            z.describe(
+              'Only include verified tokens denominated in this currency (e.g. `USD`). ' +
+                'Case-insensitive. Implies `verified=true` because the balances ' +
+                'snapshot does not store currency for unverified tokens. ' +
+                'Unknown currency strings are accepted but match no rows.',
+            ),
+          ),
+        cursor: Schema.Cursor,
+        feeEligible: z
+          .optional(Schema.booleanQuery())
+          .check(
+            z.describe(
+              'When `true`, include only tokens eligible to pay transaction fees on Tempo: ' +
+                'verified tokens that have a Fee AMM pool, plus the default fee token ' +
+                '(`pathUSD`). Use this to avoid a second `/fee-amm/pools` query when you ' +
+                'only want fee-payable holdings.',
+            ),
+            z.meta({ examples: [true] }),
+          ),
+        include: Schema.totalCountInclude,
+        limit: Schema.Limit,
+        page: Schema.Page,
+        verified: z
+          .optional(Schema.booleanQuery())
+          .check(
+            z.describe(
+              'When `true`, include only tokens from Tempo’s curated verified token list.',
+            ),
+            z.meta({ examples: [true] }),
+          ),
+      })
+      .check(
+        ...Schema.pageChecks(),
+        z.describe('Query parameters for listing an account’s token balances.'),
+      )
+
+    /**
+     * A TIP-20 token balance held by an address: the held `amount` in the
+     * token's base unit, its `formatted` value, and the trimmed `token`
+     * reference inlined per row. Rows whose token metadata cannot be resolved
+     * are omitted.
+     */
+    export const Balance = Schema.describe(
+      z.object({
+        amount: z
+          .string()
+          .check(
+            z.regex(/^\d+$/),
+            z.describe(
+              'A non-negative whole number, given as a decimal string so very large token amounts keep full precision. Expressed in the smallest unit of the token.',
+            ),
+            z.meta({ examples: ['1500000'] }),
+          ),
+        formatted: z
+          .string()
+          .check(
+            z.describe(
+              'The same balance in human-readable decimal form, using the token’s `decimals`.',
+            ),
+            z.meta({ examples: ['1.5'] }),
+          ),
+        id: z
+          .string()
+          .check(
+            z.describe(
+              'A stable resource ID for this balance, equal to the token contract address.',
+            ),
+            z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
+          ),
+        feeEligible: z
+          .optional(z.boolean())
+          .check(
+            z.describe(
+              'Whether this token can be used to pay transaction fees on Tempo: `true` when ' +
+                'the token is verified and has a Fee AMM pool, or is the default fee token ' +
+                '(`pathUSD`). Lets you identify fee-payable holdings without a separate ' +
+                '`/fee-amm/pools` query. Omitted (best-effort) when the fee-token lookup ' +
+                'is unavailable.',
+            ),
+            z.meta({ examples: [true] }),
+          ),
+        token: Tokens.schema.Token,
+      }),
+      'One TIP-20 token balance held by this account, with both raw and human-readable amounts.',
+    )
+
+    /** Page of TIP-20 token balances held by an address, ordered by amount descending. */
+    export const Response = z
+      .object({
+        data: z
+          .array(Balance)
+          .check(z.describe('The balances in this page, ordered from largest to smallest amount.')),
+        meta: z
+          .optional(Schema.CountMeta)
+          .check(z.describe('Page-level resources you requested with `include`.')),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of TIP-20 token balances held by this account.'))
+  }
+}
+
+/**
+ * Creates address-scoped balance handlers, mounted under the `/addresses`
+ * composer. Exposes `GET /:address/balances`, the held-balance page.
+ */
+export function addresses() {
+  return new Hono<App.Environment>().get(
+    '/:address/balances',
+    Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+    OpenApi.validate('param', schema.getAddressBalances.Params, {
+      code: 'address_invalid',
+      message: 'Invalid account address',
+    }),
+    OpenApi.validate('query', schema.getAddressBalances.Query, {
+      code: 'query_invalid',
+      message: 'Invalid query parameters',
+    }),
+    OpenApi.describeRoute({
+      description:
+        'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form.',
+      operationId: 'getAddressBalances',
+      responses: OpenApi.responses({
+        errors: { 502: 'The upstream indexer could not serve this request.' },
+        success: {
+          description: 'A page of token balances for this account.',
+          schema: schema.getAddressBalances.Response,
+        },
+      }),
+      summary: 'List address balances',
+      tags: ['Balances'],
+    }),
+    Cache.response<App.Environment>({
+      cacheControl: Cache.policies.noStore,
+      name: 'tempo-api:addresses:v1',
+      key: (c) => Cache.urlKey(c, schema.getAddressBalances.Query),
+    }),
+    async (c) => {
+      if (Auth.narrowAccess) return Auth.paidAccessError(c)
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'address_invalid',
+          message: 'Invalid request parameters',
+        })
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'query_invalid',
+          message: 'Invalid request parameters',
+        })
+
+      const { address } = c.req.valid('param')
+      const query = c.req.valid('query')
+
+      try {
+        const chainId = query.chainId ?? c.get('chainId')
+        // `currency` only makes sense against verified tokens, so it implies
+        // `verified=true` from the caller's perspective.
+        const verified = query.verified || query.currency !== undefined
+        const feeEligible = query.feeEligible ?? false
+
+        // The fee-token set powers both the per-row `feeEligible` flag (always)
+        // and the optional `feeEligible=true` page restriction. It is memoized
+        // per chain (a near-constant), so one read feeds the page, the count,
+        // and the row enrichment. It is a best-effort enrichment: a lookup
+        // failure omits `feeEligible` rather than failing the page — unless the
+        // caller explicitly asked to filter by `feeEligible`, where the filter
+        // can't be honored, so the failure surfaces as the declared `502`.
+        const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch((cause) => {
+          if (feeEligible) throw cause
+          return undefined
+        })
+
+        // `totalCount` (the number of matching holdings) 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')
+          ? countAddressBalances(c, {
+              address,
+              chainId,
+              currency: query.currency,
+              feeEligible,
+              feeTokens,
+              verified,
+            }).catch(() => undefined)
+          : undefined
+
+        const balances = await getAddressBalances(c, {
+          address,
+          chainId,
+          currency: query.currency,
+          cursor: query.cursor,
+          feeEligible,
+          feeTokens,
+          limit: query.limit,
+          page: query.page,
+          verified,
+        })
+
+        const meta = countPromise ? await countPromise : undefined
+
+        return c.json(
+          Response.validated(schema.getAddressBalances.Response, {
+            ...balances,
+            ...(meta ? { meta } : {}),
+          }),
+          200,
+        )
+      } catch (cause) {
+        return Response.upstream(c, cause)
+      }
+    },
+  )
+}
+
+async function getAddressBalances(
+  c: Context<App.Environment>,
+  options: getAddressBalances.Options,
+) {
+  const { address, chainId, currency, feeEligible, feeTokens, limit, verified } = options
+  const tidx = c.get('getTidx')(chainId)
+  // Keyset pagination on `(balance, token)`: balance is descending and `token`
+  // is a stable tiebreaker for the many holdings sharing a balance. A malformed
+  // cursor falls back to the head page. Note: because `balance` is mutable, this
+  // is best-effort across balance changes (the inherent limit of ranking feeds).
+  const cursor = options.cursor ? Cursor.decode(options.cursor, ['uint', '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
+
+  // Build the optional `token IN (…)` restriction before hitting TIDX. The
+  // verified/`currency` filter and the `feeEligible` filter each contribute a set
+  // of allowed addresses (`currency` matched case-insensitively so callers can
+  // type `usd`/`USD`/`Usd`); when both are present the page is their
+  // intersection. If any active filter rules every token out, return an empty
+  // page without a round trip. The snapshot is reused for the page enrichment
+  // below.
+  const snapshot = await VerifiedTokens.snapshot(c, chainId)
+  const allowed = allowedTokens({ currency, feeEligible, feeTokens, snapshot, verified })
+  const tokenFilter = allowed?.map((address) => `'${address}'`)
+  if (tokenFilter?.length === 0) return { data: [], nextCursor: null }
+
+  const holdings = await Timing.time(c, 'address_balances', async () => {
+    // A held token is one this address holds a positive amount of. Read the
+    // live `address_balances` view (`holder`-keyed: one row per
+    // `(holder, token, balance)`), which aggregates `address_holder_deltas`
+    // directly so balances reflect the indexer's chain head (no periodic
+    // snapshot refresh — see the indexer's `address_holder_deltas` MV). The
+    // `holder` equality prunes the view by its leading sort key, so this stays
+    // a bounded read per request. Fetch one extra row to detect `hasMore`
+    // without a separate count query. `startsWith` restricts results to TIP-20
+    // tokens (see `tip20AddressPrefix`) before pagination, so `hasMore`/page
+    // sizes stay correct and every returned token has resolvable metadata. The
+    // inline query is cast to `string` so TIDX treats it as a dynamic
+    // ClickHouse query that needs no event signature for the
+    // `address_balances` view.
+    //
+    // Let upstream failures propagate: this is a dedicated endpoint, so a
+    // failure should surface as the declared `502` rather than masquerade as
+    // an address holding zero tokens.
+    const keyset =
+      cursor !== undefined
+        ? ` AND ${Cursor.keyset([
+            { literal: Cursor.literal(cursor[0]!, 'uint'), name: 'balance', order: 'desc' },
+            { literal: Cursor.literal(cursor[1]!, 'address'), name: 'token', order: 'asc' },
+          ])}`
+        : ''
+    const tokenIn = tokenFilter ? ` AND token IN (${tokenFilter.join(', ')})` : ''
+
+    const result = await tidx.fetch({
+      chainId,
+      engine: 'clickhouse',
+      // `balance` is UInt256; SELECT it as a string so values > 2^53
+      // survive JSON without precision loss. The keyset cursor encodes the
+      // row's exact balance, so any rounding would re-include the cursor
+      // row on the next page. Alias is `balance_str` (not `balance`)
+      // because TIDX rejects expression aliases that shadow the source
+      // column (422).
+      query: `
+        SELECT token, toString(balance) AS balance_str
+        FROM address_balances
+        WHERE holder = '${address}' AND startsWith(token, '${tip20AddressPrefix}') AND balance > 0${tokenIn}${keyset}
+        ORDER BY balance DESC, token ASC
+        LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+      ` as string,
+    })
+
+    // The next page anchors below the last fetched row's `(balance, token)`.
+    const page = Cursor.paginate({
+      rows: result.rows,
+      limit,
+      key: (row) => {
+        const balance = Value.toIntegerString(row['balance_str'])
+        const token = Schema.Address.safeParse(row['token'])
+        return balance !== undefined && token.success ? [balance, token.data] : undefined
+      },
+    })
+
+    const data: { address: Hex.Hex; amount: string }[] = []
+    for (const row of page.rows) {
+      const token = Schema.Address.safeParse(row['token'])
+      const amount = Value.toIntegerString(row['balance_str'])
+      if (token.success && amount !== undefined) data.push({ address: token.data, amount })
+    }
+
+    return { data, nextCursor: page.nextCursor }
+  })
+
+  if (holdings.data.length === 0) return { data: [], nextCursor: holdings.nextCursor }
+
+  // Resolve token metadata for each balance. The endpoint's contract is a
+  // balance with its `token` reference inlined per row (and `formatted` needs
+  // the token `decimals`), so a row whose metadata cannot be resolved is
+  // dropped rather than returned with placeholders. Because the TIDX filter
+  // already restricts to TIP-20 (`0x20c0…`) tokens, resolution should succeed
+  // for nearly every row in practice.
+  //
+  // The verified `snapshot` fetched above is reused across the page instead of
+  // re-resolved per row. `createdAt` is not part of this endpoint's response,
+  // so it is never fetched here.
+  const resolved = await Timing.time(c, 'tokens', () =>
+    Promise.all(
+      holdings.data.map((holding) =>
+        Tokens.resolveToken(c, {
+          address: holding.address,
+          chainId,
+          snapshot,
+        })
+          .then((metadata) => ({ amount: holding.amount, metadata }) as const)
+          .catch(() => ({ amount: holding.amount, metadata: undefined }) as const),
+      ),
+    ),
+  )
+
+  const data: z.output<typeof schema.getAddressBalances.Balance>[] = []
+  for (const entry of resolved) {
+    if (!entry.metadata) continue
+    data.push({
+      amount: entry.amount,
+      formatted: core_Value.format(BigInt(entry.amount), entry.metadata.decimals),
+      id: entry.metadata.address,
+      // Best-effort: omit `feeEligible` entirely when the fee-token set was
+      // unavailable, rather than reporting a misleading `false`.
+      ...(feeTokens ? { feeEligible: feeTokens.has(entry.metadata.address.toLowerCase()) } : {}),
+      token: {
+        address: entry.metadata.address,
+        currency: entry.metadata.currency,
+        decimals: entry.metadata.decimals,
+        id: entry.metadata.id,
+        logoUri: entry.metadata.logoUri,
+        name: entry.metadata.name,
+        symbol: entry.metadata.symbol,
+        verified: entry.metadata.verified,
+      },
+    })
+  }
+
+  return { data, nextCursor: holdings.nextCursor }
+}
+
+declare namespace getAddressBalances {
+  type Options = {
+    address: z.output<typeof Schema.Address>
+    chainId: z.output<typeof Schema.ChainId>
+    /** Only include verified tokens denominated in this currency (implies `verified`). */
+    currency?: string | undefined
+    /** Opaque keyset cursor anchoring the page; omit for the head page. */
+    cursor?: string | undefined
+    /** When true, restrict the page to fee-usable tokens (members of `feeTokens`). */
+    feeEligible?: boolean | undefined
+    /**
+     * The chain's fee-token set, if resolved (best-effort): flags each row's
+     * `feeEligible` and backs the `feeEligible` filter. Undefined when the lookup
+     * failed, in which case `feeEligible` is omitted from rows.
+     */
+    feeTokens?: ReadonlySet<string> | undefined
+    limit: number
+    /** 1-indexed page number (positional pagination; exclusive with `cursor`). */
+    page?: number | undefined
+    /** When true, restrict the page to addresses in the curated verified list. */
+    verified?: boolean | undefined
+  }
+}
+
+/**
+ * Computes the optional set of allowed token addresses for the page's
+ * `token IN (…)` restriction, combining the verified/`currency` filter with the
+ * `feeEligible` filter. Each active filter contributes a candidate address list;
+ * when both are active the result is their intersection. Returns `undefined`
+ * when no filter is active (no restriction), or an empty array when an active
+ * filter excludes every token (caller short-circuits to an empty page).
+ * Addresses are lowercased to match the indexer's stored casing.
+ */
+function allowedTokens(options: allowedTokens.Options): string[] | undefined {
+  const { currency, feeEligible, feeTokens, snapshot, verified } = options
+  let allowed: string[] | undefined
+  if (verified) {
+    const matching = currency
+      ? (snapshot.byCurrency.get(currency.toLowerCase()) ?? [])
+      : snapshot.list
+    allowed = matching.map((token) => token.address.toLowerCase())
+  }
+  // The handler guarantees `feeTokens` is present whenever `feeEligible` filtering
+  // is requested (a lookup failure surfaces as a `502` instead); the `?? []`
+  // is a defensive fall-through that yields an empty page rather than silently
+  // dropping the filter.
+  if (feeEligible) {
+    if (!feeTokens) allowed = []
+    else if (allowed) allowed = allowed.filter((address) => feeTokens.has(address))
+    else allowed = Array.from(feeTokens)
+  }
+  return allowed
+}
+
+declare namespace allowedTokens {
+  type Options = {
+    /** Only include verified tokens denominated in this currency (implies `verified`). */
+    currency?: string | undefined
+    /** When true, restrict to fee-usable tokens (members of `feeTokens`). */
+    feeEligible?: boolean | undefined
+    /** The chain's fee-token set, if resolved (best-effort). */
+    feeTokens?: ReadonlySet<string> | undefined
+    /** Compiled verified-token snapshot for the chain. */
+    snapshot: VerifiedTokens.Snapshot
+    /** When true, restrict to addresses in the curated verified list. */
+    verified?: boolean | undefined
+  }
+}
+
+/**
+ * Exact count of an address's matching TIP-20 holdings, sharing
+ * {@link getAddressBalances}'s `holder`/`verified`/`currency` filters (minus
+ * pagination) so the count matches the page it annotates. The `holder` equality
+ * prunes the `token_balances_snapshot` view by its sort key, so ClickHouse
+ * counts via the sparse primary index without a row scan — the count is exact
+ * and cheap with no cap (`totalCountCapped` is always `false`), verified at
+ * ~370k holdings in <1s. Feeds the opt-in `meta.totalCount`.
+ */
+async function countAddressBalances(
+  c: Context<App.Environment>,
+  options: countAddressBalances.Options,
+): Promise<{ totalCountCapped: boolean; totalCount: number }> {
+  const { address, chainId, currency, feeEligible, feeTokens, verified } = options
+  const tidx = c.get('getTidx')(chainId)
+
+  // Same verified/currency/feeEligible `token IN (…)` restriction as the page; an
+  // empty filter means nothing matches, so the count is zero without a round
+  // trip.
+  const snapshot = await VerifiedTokens.snapshot(c, chainId)
+  const allowed = allowedTokens({ currency, feeEligible, feeTokens, snapshot, verified })
+  const tokenFilter = allowed?.map((address) => `'${address}'`)
+  if (tokenFilter?.length === 0) return { totalCountCapped: false, totalCount: 0 }
+  const tokenIn = tokenFilter ? ` AND token IN (${tokenFilter.join(', ')})` : ''
+
+  return Timing.time(c, 'address_balances_count', async () => {
+    // Exact count over the holder-pruned `address_balances` rows (mirrors the
+    // page's WHERE, minus the keyset cursor). The `holder` sort-key prune lets
+    // ClickHouse count via the sparse index, so no cap is needed. The inline
+    // query is cast to `string` so TIDX treats it as a dynamic ClickHouse
+    // query needing no signature.
+    const result = await tidx.fetch({
+      chainId,
+      engine: 'clickhouse',
+      query: `
+        SELECT count(*) AS total
+        FROM address_balances
+        WHERE holder = '${address}' AND startsWith(token, '${tip20AddressPrefix}') AND balance > 0${tokenIn}
+      ` as string,
+    })
+    const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0
+    return { totalCountCapped: false, totalCount }
+  })
+}
+
+declare namespace countAddressBalances {
+  type Options = {
+    address: z.output<typeof Schema.Address>
+    chainId: z.output<typeof Schema.ChainId>
+    /** Only include verified tokens denominated in this currency (implies `verified`). */
+    currency?: string | undefined
+    /** When true, restrict the count to fee-usable tokens (members of `feeTokens`). */
+    feeEligible?: boolean | undefined
+    /** The chain's fee-token set (best-effort), backing the `feeEligible` restriction. */
+    feeTokens?: ReadonlySet<string> | undefined
+    /** When true, restrict the count to addresses in the curated verified list. */
+    verified?: boolean | undefined
+  }
+}