tapimo 0.12.0 → 0.13.0

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

@@ -87,104 +87,117 @@ export namespace schema {
       )
 
     /** A TIP-20 balance with raw and formatted amounts. Unresolvable token metadata omits the row. */
-    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.',
+    export const Balance = OpenApi.component(
+      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'] }),
             ),
-            z.meta({ examples: ['1500000'] }),
-          ),
-        currency: z
-          .string()
-          .check(
-            z.describe(
-              'The currency label for this balance, such as `USD` for a USD-denominated token.',
+          currency: z
+            .string()
+            .check(
+              z.describe(
+                'The currency label for this balance, such as `USD` for a USD-denominated token.',
+              ),
+              z.meta({ examples: ['USD'] }),
             ),
-            z.meta({ examples: ['USD'] }),
-          ),
-        decimals: z
-          .number()
-          .check(
-            z.int(),
-            z.nonnegative(),
-            z.describe(
-              'The number of decimal places used to convert this balance between base units and human-readable form.',
+          decimals: z
+            .number()
+            .check(
+              z.int(),
+              z.nonnegative(),
+              z.describe(
+                'The number of decimal places used to convert this balance between base units and human-readable form.',
+              ),
+              z.meta({ examples: [6] }),
             ),
-            z.meta({ examples: [6] }),
-          ),
-        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.',
+          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] }),
             ),
-            z.meta({ examples: [true] }),
-          ),
-        formatted: z
-          .string()
-          .check(
-            z.describe(
-              'The same balance in human-readable decimal form, using this balance’s `decimals`.',
+          formatted: z
+            .string()
+            .check(
+              z.describe(
+                'The same balance in human-readable decimal form, using this balance’s `decimals`.',
+              ),
+              z.meta({ examples: ['1.5'] }),
             ),
-            z.meta({ examples: ['1.5'] }),
-          ),
-        id: z
-          .string()
-          .check(
-            z.describe(
-              'A stable resource ID for this balance, equal to the token contract address.',
+          id: z
+            .string()
+            .check(
+              z.describe(
+                'A stable resource ID for this balance, equal to the token contract address.',
+              ),
+              z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
             ),
-            z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
-          ),
-        token: Tokens.schema.Token,
-        valuation: z
-          .optional(z.nullable(Valuation.schema.Value))
-          .check(
-            z.describe(
-              '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.',
+          token: Tokens.schema.Token,
+          valuation: z
+            .optional(z.nullable(Valuation.schema.Value))
+            .check(
+              z.describe(
+                '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.',
+              ),
             ),
-          ),
-      }),
-      'One TIP-20 token balance held by this account, with both raw and human-readable amounts.',
+        }),
+        'One TIP-20 token balance held by this account, with both raw and human-readable amounts.',
+      ),
+      'Balance',
     )
 
     /** Page-level resources: opt-in counts plus valuation rate provenance. */
-    export const Meta = z
-      .object({
-        valuation: z
-          .optional(Valuation.schema.Pricing)
-          .check(
-            z.describe(
-              'Rate provenance for row valuations. Present when conversion rates were ' +
-                'consulted; absent when every value was identity-valued or rates were unavailable.',
+    export const Meta = OpenApi.component(
+      z
+        .object({
+          valuation: z
+            .optional(Valuation.schema.Pricing)
+            .check(
+              z.describe(
+                'Rate provenance for row valuations. Present when conversion rates were ' +
+                  'consulted; absent when every value was identity-valued or rates were unavailable.',
+              ),
             ),
-          ),
-        totalCount: z.optional(Schema.TotalCount),
-        totalCountCapped: z.optional(Schema.TotalCountCapped),
-      })
-      .check(z.describe('Page-level resources attached to this response.'))
+          totalCount: z.optional(Schema.TotalCount),
+          totalCountCapped: z.optional(Schema.TotalCountCapped),
+        })
+        .check(z.describe('Page-level resources attached to this response.')),
+      'BalanceListMeta',
+    )
 
     /** 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(Meta)
-          .check(z.describe('Page-level resources: opt-in counts and valuation rate provenance.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of TIP-20 token balances held by this account.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(Balance)
+            .check(
+              z.describe('The balances in this page, ordered from largest to smallest amount.'),
+            ),
+          meta: z
+            .optional(Meta)
+            .check(
+              z.describe('Page-level resources: opt-in counts and valuation rate provenance.'),
+            ),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of TIP-20 token balances held by this account.')),
+      'BalanceList',
+    )
   }
 
   /** Schemas for the getAddressBalance operation. */
@@ -213,9 +226,7 @@ export namespace schema {
       .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.'),
-    )
+    export const Response = getAddressBalances.Balance
   }
 }
 
@@ -242,7 +253,17 @@ export function addresses(options: addresses.Options = {}) {
           '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.' },
+          errors: {
+            400: {
+              codes: [
+                'address_invalid',
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'query_invalid',
+              ],
+            },
+            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,
@@ -318,6 +339,14 @@ export function addresses(options: addresses.Options = {}) {
         operationId: 'getAddressBalance',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: [
+                'address_invalid',
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'query_invalid',
+              ],
+            },
             404: {
               description: 'The token is not a registered TIP-20 token.',
               codes: ['token_not_found'],
@@ -517,16 +546,23 @@ async function getAddressBalances(
     const caller = c.get('zones').has(chainId) ? address : undefined
     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.
+      // deployless multicall. Missing contracts are stale indexed candidates;
+      // other read failures still fail the request.
       const results = await Promise.all(
         holdings.map(async (holding) => {
-          const call = Actions.token.getBalance.call(client, {
-            account: address,
-            token: holding.address,
-          })
-          const amount = await client.readContract({ ...call, account: caller })
-          return amount === 0n ? undefined : { address: holding.address, amount: amount.toString() }
+          try {
+            const call = Actions.token.getBalance.call(client, {
+              account: address,
+              token: holding.address,
+            })
+            const amount = await client.readContract({ ...call, account: caller })
+            return amount === 0n
+              ? undefined
+              : { address: holding.address, amount: amount.toString() }
+          } catch (cause) {
+            if (!(await client.getCode({ address: holding.address }))) return undefined
+            throw cause
+          }
         }),
       )
       const rows = results.filter((holding) => holding !== undefined)