tapimo 0.4.4 → 0.5.0

package/src/apps/data/routes/balances.ts

@@ -1,5 +1,5 @@
 import { Hono, type Context } from 'hono'
-import { Hex, Value as core_Value } from 'ox'
+import { Value as core_Value } from 'ox'
 import { Actions } from 'viem/tempo'
 import * as z from 'zod/mini'
 
@@ -11,16 +11,14 @@ 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.
+// balance sources include every Transfer-emitting contract, so discovery
+// filters on this prefix to keep non-TIP-20 tokens out of results.
 const tip20AddressPrefix = '0x20c0'
 
 /** Zod schemas owned by the balance handlers. */
@@ -215,20 +213,6 @@ export function addresses() {
           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,
@@ -236,20 +220,13 @@ export function addresses() {
           cursor: query.cursor,
           feeEligible,
           feeTokens,
+          includeTotalCount: query.include.includes('totalCount'),
           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,
-        )
+        return c.json(Response.validated(schema.getAddressBalances.Response, balances), 200)
       } catch (cause) {
         return Response.upstream(c, cause)
       }
@@ -261,18 +238,11 @@ async function getAddressBalances(
   c: Context<App.Environment>,
   options: getAddressBalances.Options,
 ) {
-  const { address, chainId, currency, feeEligible, feeTokens, limit, verified } = options
+  const { address, chainId, currency, feeEligible, feeTokens, includeTotalCount, 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
+  const offset = options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : 0
 
   // Build the optional `token IN (…)` restriction before hitting TIDX. The
   // verified/`currency` filter and the `feeEligible` filter each contribute a set
@@ -284,98 +254,56 @@ async function getAddressBalances(
   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 }
+  if (tokenFilter?.length === 0)
+    return {
+      data: [],
+      ...(includeTotalCount ? { meta: { totalCount: 0, totalCountCapped: false } } : {}),
+      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 holdings = await Timing.time(c, 'balances_discovery', async () => {
     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).
+      // Discovery tolerates stale and reorged rows: RPC removes candidates
+      // with no current balance, so avoid the cost of `FINAL` and aggregation.
       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}` : ''}
+        SELECT DISTINCT token
+        FROM address_holder_deltas
+        WHERE holder = '${address}' AND startsWith(token, '${tip20AddressPrefix}')${tokenIn}
       ` 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) {
+    return result.rows.flatMap((row) => {
       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 }
+      return token.success ? [{ address: token.data }] : []
+    })
   })
 
-  if (holdings.data.length === 0) return { data: [], nextCursor: holdings.nextCursor }
+  if (holdings.length === 0)
+    return {
+      data: [],
+      ...(includeTotalCount ? { meta: { totalCount: 0, totalCountCapped: false } } : {}),
+      nextCursor: null,
+    }
 
   const client = c.get('getClient')(chainId)
-  // TODO: remove once https://github.com/tempoxyz/tidx/commit/2f37b44172d381fd00234ef23f79ed1e1d69c470 deployed.
   const corrected = await Timing.time(c, 'balances_rpc', async () => {
-    const results = await client
-      .multicall({
-        allowFailure: true,
-        contracts: holdings.data.map((holding) =>
-          Actions.token.getBalance.call(client, { account: address, token: holding.address }),
-        ),
-      })
-      .catch(() => undefined)
-
-    const rows: { address: Hex.Hex; amount: string }[] = []
-    for (const [index, holding] of holdings.data.entries()) {
-      const result = results?.[index]
-      if (!result || result.status !== 'success' || typeof result.result !== 'bigint') {
-        rows.push(holding)
-        continue
-      }
-      if (result.result === 0n) continue
-      rows.push({ address: holding.address, amount: result.result.toString() })
-    }
+    // Concurrent reads enter viem's shared batch window and become one
+    // deployless multicall. A failed read fails the request rather than serving
+    // a stale or partial balance page.
+    const results = await Promise.all(
+      holdings.map(async (holding) => {
+        const { amount } = await Actions.token.getBalance(client, {
+          account: address,
+          token: holding.address,
+        })
+        return amount === 0n ? undefined : { address: holding.address, amount: amount.toString() }
+      }),
+    )
+    const rows = results.filter((holding) => holding !== undefined)
 
     rows.sort((a, b) => {
       const delta = BigInt(b.amount) - BigInt(a.amount)
@@ -385,7 +313,30 @@ async function getAddressBalances(
     return rows
   })
 
-  if (corrected.length === 0) return { data: [], nextCursor: holdings.nextCursor }
+  const positioned = (() => {
+    if (!cursor) return corrected.slice(offset)
+    const amount = BigInt(cursor[0]!)
+    const address = String(cursor[1]!)
+    return corrected.filter(
+      (holding) =>
+        BigInt(holding.amount) < amount ||
+        (BigInt(holding.amount) === amount && holding.address > address),
+    )
+  })()
+  const page = Cursor.paginate({
+    rows: positioned,
+    limit,
+    key: (holding) => [holding.amount, holding.address],
+  })
+
+  if (page.rows.length === 0)
+    return {
+      data: [],
+      ...(includeTotalCount
+        ? { meta: { totalCount: corrected.length, totalCountCapped: false } }
+        : {}),
+      nextCursor: page.nextCursor,
+    }
 
   // Resolve token metadata for each balance. The endpoint's contract is a
   // balance with its `token` reference inlined per row (and `formatted` needs
@@ -399,7 +350,7 @@ async function getAddressBalances(
   // so it is never fetched here.
   const resolved = await Timing.time(c, 'tokens', () =>
     Promise.all(
-      corrected.map((holding) =>
+      page.rows.map((holding) =>
         Tokens.resolveToken(c, {
           address: holding.address,
           chainId,
@@ -434,7 +385,13 @@ async function getAddressBalances(
     })
   }
 
-  return { data, nextCursor: holdings.nextCursor }
+  return {
+    data,
+    ...(includeTotalCount
+      ? { meta: { totalCount: corrected.length, totalCountCapped: false } }
+      : {}),
+    nextCursor: page.nextCursor,
+  }
 }
 
 declare namespace getAddressBalances {
@@ -453,6 +410,8 @@ declare namespace getAddressBalances {
      * failed, in which case `feeEligible` is omitted from rows.
      */
     feeTokens?: ReadonlySet<string> | undefined
+    /** When true, include the corrected candidate count in response metadata. */
+    includeTotalCount: boolean
     limit: number
     /** 1-indexed page number (positional pagination; exclusive with `cursor`). */
     page?: number | undefined
@@ -505,63 +464,3 @@ declare namespace allowedTokens {
     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
-  }
-}

package/src/apps/data/routes/blocks.ts

@@ -584,9 +584,8 @@ export function blocks() {
  * `GET /v1/blocks/:block` with an ISO 8601 selector.
  *
  * Like the original it searches a ±{@link byTimestampWindowSeconds}s window and
- * returns `404` when no indexed block falls within it. Because the chain id is a
- * path parameter (not the `chainId` query the global guard inspects), this
- * validates it against the deployment's supported chains itself.
+ * returns `404` when no indexed block falls within it. A local supported-chain
+ * check keeps standalone composition safe.
  */
 export function blocksByTimestampCompat() {
   return new Hono<App.Environment>().get(
@@ -635,8 +634,7 @@ export function blocksByTimestampCompat() {
       const { chainId } = c.req.valid('param')
       const { closest, timestamp } = c.req.valid('query')
 
-      // The global unsupported-chain guard only inspects the `chainId` query, so
-      // reject an unserved chain here before it reaches the indexer.
+      // Keep this route safe when mounted without the shared data app.
       const supportedChainIds = c.get('supportedChainIds')
       if (!supportedChainIds.has(chainId))
         return Response.unsupportedChainId(c, chainId, supportedChainIds)

package/src/apps/data/routes/coingecko.ts

@@ -466,14 +466,8 @@ export namespace schema {
 }
 
 /**
- * Composes the GeckoTerminal/CoinGecko DEX-integration compatibility adapter.
- */
-/**
- * Rejects a path `chainId` this deployment does not serve. GeckoTerminal
- * templates `chainId` into the path, so the App-level query-param guard never
- * sees it; reject a well-formed-but-unsupported chain here before it reaches an
- * upstream (which would otherwise surface as an opaque `upstream_error`).
- * Malformed values fall through to each route's own `param` validation.
+ * Keeps a local supported-chain check when this route group is composed
+ * independently of the shared data app.
  */
 const guardChainId = createMiddleware<App.Environment>(async (c, next) => {
   const parsed = Schema.ChainId.safeParse(c.req.param('chainId'))
@@ -482,6 +476,7 @@ const guardChainId = createMiddleware<App.Environment>(async (c, next) => {
   return Response.unsupportedChainId(c, parsed.data, supported)
 })
 
+/** Composes the GeckoTerminal/CoinGecko DEX-integration compatibility adapter. */
 export function coingecko() {
   return new Hono<App.Environment>()
     .use('/gecko/:chainId/*', guardChainId)