tapimo 0.8.0 → 0.10.0

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

@@ -66,7 +66,12 @@ export namespace schema {
         include: Schema.totalCountInclude,
         limit: Schema.Limit,
         page: Schema.Page,
-        'valuation.currency': Schema.Denomination,
+        'valuation.currency': Schema.Denomination.check(
+          z.describe(
+            'When present, include each holding’s nominal value in this denomination. ' +
+              'Case-insensitive and must be priced by the configured FX oracle.',
+          ),
+        ),
         verified: z
           .optional(Schema.booleanQuery())
           .check(
@@ -141,11 +146,11 @@ export namespace schema {
           ),
         token: Tokens.schema.Token,
         valuation: z
-          .nullable(Valuation.schema.Value)
+          .optional(z.nullable(Valuation.schema.Value))
           .check(
             z.describe(
-              'The holding’s nominal value in the requested `valuation.currency`, or `null` when the ' +
-                'token is unverified, its display currency has no rate, or rates were unavailable.',
+              'The holding’s nominal value when `valuation.currency` is requested, or `null` when ' +
+                'the token is unverified, its display currency has no rate, or rates were unavailable.',
             ),
           ),
       }),
@@ -181,102 +186,241 @@ export namespace schema {
       })
       .check(z.describe('A page of TIP-20 token balances held by this account.'))
   }
+
+  /** Schemas for the getAddressBalance operation. */
+  export namespace getAddressBalance {
+    /** Path parameters for a single address balance request. */
+    export const Params = z
+      .object({
+        address: Schema.Address.check(
+          z.describe('The account address whose token balance you want to read.'),
+        ),
+        token: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address.')),
+      })
+      .check(z.describe('Path parameters for reading one account token balance.'))
+
+    /** Query parameters for a single address balance request. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        'valuation.currency': Schema.Denomination.check(
+          z.describe(
+            'When present, include the holding’s nominal value in this denomination. ' +
+              'Case-insensitive and must be priced by the configured FX oracle.',
+          ),
+        ),
+      })
+      .check(z.describe('Query parameters for reading one account token balance.'))
+
+    /** A single TIP-20 token balance held by an address. */
+    export const Response = getAddressBalances.Balance.check(
+      z.describe('One TIP-20 token balance held by this account.'),
+    )
+  }
 }
 
 /**
  * Creates address-scoped balance handlers, mounted under the `/addresses`
- * composer. Exposes `GET /:address/balances`, the held-balance page.
+ * composer. Exposes the held-balance page and individual token balances.
  */
 export function addresses(options: addresses.Options = {}) {
   const oracle = options.fx?.oracle ?? FxOracle.ecb()
-  return new Hono<App.Environment>().get(
-    '/v1/addresses/: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, and each verified holding carries its nominal value in the requested denomination.',
-      operationId: 'getAddressBalances',
-      responses: OpenApi.responses({
-        errors: { 502: 'Could not read balance or token data from an upstream service.' },
-        success: {
-          description: 'A page of token balances for this account.',
-          schema: schema.getAddressBalances.Response,
-        },
+  return new Hono<App.Environment>()
+    .get(
+      '/v1/addresses/: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',
       }),
-      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 {
+      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. Pass `valuation.currency` to include nominal values.',
+        operationId: 'getAddressBalances',
+        responses: OpenApi.responses({
+          errors: { 502: 'Could not read balance or token data from an upstream service.' },
+          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
+
+          const balances = await getAddressBalances(c, {
+            address,
+            chainId,
+            currency: query.currency,
+            cursor: query.cursor,
+            denomination: query['valuation.currency'],
+            feeEligible,
+            includeTotalCount: query.include.includes('totalCount'),
+            limit: query.limit,
+            oracle,
+            page: query.page,
+            verified,
+          })
+
+          return c.json(Response.validated(schema.getAddressBalances.Response, balances), 200)
+        } catch (cause) {
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/addresses/:address/balances/:token',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getAddressBalance.Params, {
+        code: 'address_invalid',
+        message: 'Invalid address or token address',
+      }),
+      OpenApi.validate('query', schema.getAddressBalance.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Returns the live balance of one TIP-20 token held by an account, including token metadata and a human-readable amount.',
+        operationId: 'getAddressBalance',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              description: 'The token is not a registered TIP-20 token.',
+              codes: ['token_not_found'],
+            },
+            502: 'Could not read balance or token data from an upstream service.',
+          },
+          success: {
+            description: 'The requested token balance for this account.',
+            schema: schema.getAddressBalance.Response,
+          },
+        }),
+        summary: 'Get address balance',
+        tags: ['Balances'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.noStore,
+        name: 'tempo-api:addresses:v1',
+        key: (c) => Cache.urlKey(c, schema.getAddressBalance.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, token } = c.req.valid('param')
+        const query = c.req.valid('query')
         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
-        })
-
-        const balances = await getAddressBalances(c, {
-          address,
-          chainId,
-          currency: query.currency,
-          cursor: query.cursor,
-          denomination: query['valuation.currency'] ?? 'USD',
-          feeEligible,
-          feeTokens,
-          includeTotalCount: query.include.includes('totalCount'),
-          limit: query.limit,
-          oracle,
-          page: query.page,
-          verified,
-        })
-
-        return c.json(Response.validated(schema.getAddressBalances.Response, balances), 200)
-      } catch (cause) {
-        if (cause instanceof Valuation.UnsupportedDenominationError)
-          return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
-        return Response.upstream(c, cause)
-      }
-    },
-  )
+        const denomination = query['valuation.currency']
+
+        try {
+          const rates = denomination
+            ? await Valuation.rateSet(c, oracle)
+                .then((rates) => {
+                  if (denomination !== rates.base && rates.rates[denomination] === undefined)
+                    throw new Valuation.UnsupportedDenominationError(denomination, oracle.name)
+                  return rates
+                })
+                .catch((cause) => {
+                  if (cause instanceof Valuation.UnsupportedDenominationError) throw cause
+                  return undefined
+                })
+            : undefined
+          const snapshotPromise = VerifiedTokens.snapshot(c, chainId)
+          const resolvedTokenPromise = snapshotPromise.then((snapshot) =>
+            Timing.time(c, 'token', () =>
+              Tokens.resolveToken(c, { address: token, chainId, include: [], snapshot }),
+            ),
+          )
+          const [balance, feeTokens, snapshot, resolvedToken] = await Promise.all([
+            Timing.time(c, 'balance_rpc', async () => {
+              const result = await Actions.token.getBalance(c.get('getClient')(chainId), {
+                account: address,
+                token,
+              })
+              return result.amount
+            }),
+            FeeAmm.feeTokenSet(c, chainId).catch(() => undefined),
+            snapshotPromise,
+            resolvedTokenPromise,
+          ])
+          return c.json(
+            Response.validated(schema.getAddressBalance.Response, {
+              amount: balance.toString(),
+              currency: resolvedToken.currency,
+              decimals: resolvedToken.decimals,
+              ...(feeTokens ? { feeEligible: feeTokens.has(token) } : {}),
+              formatted: core_Value.format(balance, resolvedToken.decimals),
+              id: token,
+              token: resolvedToken,
+              ...(denomination
+                ? {
+                    valuation: Valuation.valuationFor({
+                      amount: balance,
+                      denomination,
+                      rates,
+                      token: snapshot.byAddress.get(token),
+                    }),
+                  }
+                : {}),
+            }),
+            200,
+          )
+        } catch (cause) {
+          if (Tokens.isTokenNotFound(cause))
+            return Response.error(c, {
+              code: 'token_not_found',
+              message: 'Token not found',
+              status: 404,
+            })
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
 }
 
 export declare namespace addresses {
@@ -297,7 +441,6 @@ async function getAddressBalances(
     currency,
     denomination,
     feeEligible,
-    feeTokens,
     includeTotalCount,
     limit,
     oracle,
@@ -307,8 +450,9 @@ async function getAddressBalances(
   const cursor = options.cursor ? Cursor.decode(options.cursor, ['uint', 'address']) : undefined
   const offset = options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : 0
 
-  // Validate the requested denomination independently of the current page.
-  await Valuation.ratesFor(c, { currencies: [], denomination, oracle })
+  // Validate an explicit denomination before balance discovery and correction
+  // so dependency failures cannot mask a caller error.
+  if (denomination) await Valuation.ratesFor(c, { currencies: [], denomination, oracle })
 
   // Build the optional `token IN (…)` restriction before hitting TIDX. The
   // verified/`currency` filter and the `feeEligible` filter each contribute a set
@@ -317,17 +461,32 @@ async function getAddressBalances(
   // 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 snapshotPromise = VerifiedTokens.snapshot(c, chainId)
+  // Fee filtering can fail before the concurrently started snapshot is awaited.
+  // Observing this branch prevents an unhandled rejection; the later await still propagates it.
+  void snapshotPromise.catch(() => undefined)
+  const [snapshot_filter, feeTokens_filter] = await Promise.all([
+    verified ? snapshotPromise : Promise.resolve(undefined),
+    feeEligible ? FeeAmm.feeTokenSet(c, chainId) : Promise.resolve(undefined),
+  ])
+  const allowed = allowedTokens({
+    currency,
+    feeEligible,
+    feeTokens: feeTokens_filter,
+    snapshot: snapshot_filter,
+    verified,
+  })
   const tokenFilter = allowed?.map((address) => `'${address}'`)
-  if (tokenFilter?.length === 0)
+  if (tokenFilter?.length === 0) {
+    await snapshotPromise
     return {
       data: [],
       ...(includeTotalCount ? { meta: { totalCount: 0, totalCountCapped: false } } : {}),
       nextCursor: null,
     }
+  }
 
-  const holdings = await Timing.time(c, 'balances_discovery', async () => {
+  const holdingsPromise = Timing.time(c, 'balances_discovery', async () => {
     const tokenIn = tokenFilter ? ` AND token IN (${tokenFilter.join(', ')})` : ''
 
     const result = await tidx.fetch({
@@ -348,36 +507,54 @@ async function getAddressBalances(
     })
   })
 
-  if (holdings.length === 0)
+  // Correction starts as soon as discovery completes. Snapshot and fee-token
+  // cache misses continue concurrently until enrichment needs their results.
+  const correctedPromise = holdingsPromise.then(async (holdings) => {
+    if (holdings.length === 0) return []
+    const client = c.get('getClient')(chainId)
+    return Timing.time(c, 'balances_rpc', async () => {
+      // 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)
+        if (delta !== 0n) return delta > 0n ? 1 : -1
+        return a.address < b.address ? -1 : a.address > b.address ? 1 : 0
+      })
+      return rows
+    })
+  })
+  const feeTokensPromise = feeEligible
+    ? Promise.resolve(feeTokens_filter)
+    : holdingsPromise.then((holdings) =>
+        holdings.length === 0 ? undefined : FeeAmm.feeTokenSet(c, chainId).catch(() => undefined),
+      )
+
+  const [holdings, snapshot, feeTokens, corrected] = await Promise.all([
+    holdingsPromise,
+    snapshotPromise,
+    feeTokensPromise,
+    correctedPromise,
+  ])
+
+  if (holdings.length === 0) {
     return {
       data: [],
       ...(includeTotalCount ? { meta: { totalCount: 0, totalCountCapped: false } } : {}),
       nextCursor: null,
     }
-
-  const client = c.get('getClient')(chainId)
-  const corrected = await Timing.time(c, 'balances_rpc', async () => {
-    // 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)
-      if (delta !== 0n) return delta > 0n ? 1 : -1
-      return a.address < b.address ? -1 : a.address > b.address ? 1 : 0
-    })
-    return rows
-  })
+  }
 
   const positioned = (() => {
     if (!cursor) return corrected.slice(offset)
@@ -395,7 +572,7 @@ async function getAddressBalances(
     key: (holding) => [holding.amount, holding.address],
   })
 
-  if (page.rows.length === 0)
+  if (page.rows.length === 0) {
     return {
       data: [],
       ...(includeTotalCount
@@ -403,22 +580,38 @@ async function getAddressBalances(
         : {}),
       nextCursor: page.nextCursor,
     }
+  }
 
-  const rates = await Valuation.ratesFor(c, {
-    currencies: page.rows.flatMap((row) => {
-      const held = snapshot.byAddress.get(row.address.toLowerCase())?.currency
-      return held === undefined ? [] : [held]
-    }),
-    denomination,
-    oracle,
-  })
+  const ratesPromise = denomination
+    ? Valuation.ratesFor(c, {
+        currencies: page.rows.flatMap((row) => {
+          const held = snapshot.byAddress.get(row.address.toLowerCase())?.currency
+          return held === undefined ? [] : [held]
+        }),
+        denomination,
+        oracle,
+      })
+    : Promise.resolve(undefined)
 
   // Balance tokens retain their logo and verification metadata by default.
-  const resolved = await Timing.time(c, 'tokens', () =>
+  const resolvedPromise = Timing.time(c, 'tokens', () =>
     Promise.all(
       page.rows.map(async (holding) => {
         try {
           const token = Schema.Address.parse(holding.address.toLowerCase())
+          const verifiedToken = snapshot.byAddress.get(token)
+          // The curated list owns verified-token metadata, but uploaded logos live only in the asset store.
+          if (verifiedToken)
+            return {
+              amount: holding.amount,
+              logoUri:
+                verifiedToken.logoUri ??
+                (await Timing.time(c, 'token_logo', () =>
+                  Tokens.getTokenLogo(c, { address: token, chainId }),
+                ).catch(() => undefined)),
+              metadata: verifiedToken,
+              token,
+            }
           const [logoUri, metadata] = await Promise.all([
             Timing.time(c, 'token_logo', () =>
               Tokens.getTokenLogo(c, { address: token, chainId }),
@@ -434,6 +627,7 @@ async function getAddressBalances(
       }),
     ),
   )
+  const [rates, resolved] = await Promise.all([ratesPromise, resolvedPromise])
 
   const data: z.output<typeof schema.getAddressBalances.Balance>[] = []
   for (const entry of resolved) {
@@ -458,12 +652,16 @@ async function getAddressBalances(
         symbol: entry.metadata.symbol,
         verified: snapshot.byAddress.has(entry.token),
       },
-      valuation: Valuation.valuationFor({
-        amount: BigInt(entry.amount),
-        denomination,
-        rates,
-        token: snapshot.byAddress.get(entry.token),
-      }),
+      ...(denomination
+        ? {
+            valuation: Valuation.valuationFor({
+              amount: BigInt(entry.amount),
+              denomination,
+              rates,
+              token: snapshot.byAddress.get(entry.token),
+            }),
+          }
+        : {}),
     })
   }
 
@@ -487,15 +685,9 @@ declare namespace getAddressBalances {
     /** Opaque keyset cursor anchoring the page; omit for the head page. */
     cursor?: string | undefined
     /** Currency the per-row valuations are denominated in (uppercase). */
-    denomination: string
-    /** When true, restrict the page to fee-usable tokens (members of `feeTokens`). */
+    denomination?: string | undefined
+    /** When true, restrict the page to fee-usable tokens. */
     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
     /** When true, include the corrected candidate count in response metadata. */
     includeTotalCount: boolean
     limit: number

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

@@ -232,20 +232,26 @@ describe('GET /blocks', () => {
 
 describe('GET /blocks/:block (ISO 8601 timestamp)', () => {
   test('resolves an ISO 8601 timestamp to the first block at or after it', async () => {
-    expect(recent).toBeDefined()
-    const recentBlock = await Viem.getClient().getBlock({ blockNumber: recent!.number })
-    const seconds = Number(recentBlock.timestamp)
-    const iso = new Date(seconds * 1000).toISOString()
     const client = TestApp.client()
+    // Seed from TIDX rather than the RPC head, which can advance beyond the
+    // indexer's timestamp lookup watermark.
+    const blocksResponse = await client.v1.blocks.$get({ query: { limit: '5' } }, TestApp.auth)
+    const blocks = await TestApp.json(blocksResponse, Blocks.schema.getBlocks.Response)
+    const indexed = blocks.data[0]
+    expect(blocksResponse.status).toBe(200)
+    expect(indexed).toBeDefined()
+
     const response = await client.v1.blocks[':block'].$get(
-      { param: { block: iso }, query: {} },
+      { param: { block: indexed!.timestamp }, query: {} },
       TestApp.auth,
     )
     const body = await TestApp.json(response, Blocks.schema.getBlock.Response)
     expect(response.status).toBe(200)
     expect(typeof body.number).toBe('number')
     // The returned block's timestamp must be >= the requested timestamp.
-    expect(new Date(body.timestamp).getTime() / 1000).toBeGreaterThanOrEqual(seconds)
+    expect(new Date(body.timestamp).getTime()).toBeGreaterThanOrEqual(
+      new Date(indexed!.timestamp).getTime(),
+    )
   })
 
   test('returns 404 for a far-future timestamp with no indexed block', async () => {