tapimo 0.14.0 → 0.15.0

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

@@ -106,12 +106,15 @@ export namespace schema {
    * checksummed addresses, so response bodies keep the checksum produced by
    * `Address.checksum`.
    */
-  export const ChecksummedAddress = z
-    .string()
-    .check(
-      z.regex(/^0x[0-9a-fA-F]{40}$/),
-      z.describe('Checksummed 0x-prefixed 20-byte account or contract address.'),
-    )
+  export const ChecksummedAddress = OpenApi.component(
+    z
+      .string()
+      .check(
+        z.regex(/^0x[0-9a-fA-F]{40}$/),
+        z.describe('Checksummed 0x-prefixed 20-byte account or contract address.'),
+      ),
+    'CoinGeckoAddress',
+  )
 
   /**
    * Path `chainId`. Unlike the rest of Tempo API (where `chainId` is an optional
@@ -129,32 +132,38 @@ export namespace schema {
     )
 
   /** Indexed-block tip exposed to GeckoTerminal. */
-  export const Block = Schema.describe(
-    z.object({
-      blockNumber: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Block number on Tempo.'),
-          z.meta({ examples: [23456789] }),
-        ),
-      blockTimestamp: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Block time as Unix seconds.'),
-          z.meta({ examples: [1718668800] }),
-        ),
-    }),
-    'A Tempo block reference with its number and timestamp.',
+  export const Block = OpenApi.component(
+    Schema.describe(
+      z.object({
+        blockNumber: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Block number on Tempo.'),
+            z.meta({ examples: [23456789] }),
+          ),
+        blockTimestamp: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Block time as Unix seconds.'),
+            z.meta({ examples: [1718668800] }),
+          ),
+      }),
+      'A Tempo block reference with its number and timestamp.',
+    ),
+    'CoinGeckoBlock',
   )
 
   /** `GET /:chainId/latest-block` response. */
-  export const LatestBlockResponse = Schema.describe(
-    z.object({ block: Block }),
-    'The newest Tempo block that has been indexed for CoinGecko-compatible data.',
+  export const LatestBlockResponse = OpenApi.component(
+    Schema.describe(
+      z.object({ block: Block }),
+      'The newest Tempo block that has been indexed for CoinGecko-compatible data.',
+    ),
+    'CoinGeckoLatestBlockResponse',
   )
 
   /** Path parameters addressing a single asset. */
@@ -168,158 +177,173 @@ export namespace schema {
     .check(z.describe('Path values that select a TIP-20 asset on a Tempo network.'))
 
   /** A TIP-20 asset in GeckoTerminal shape. */
-  export const Asset = Schema.describe(
-    z.object({
-      id: schema.ChecksummedAddress.check(
-        z.describe('Checksummed TIP-20 token contract address.'),
-        z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
-      ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable token name.'), z.meta({ examples: ['Tempo USD'] })),
-      symbol: z
-        .string()
-        .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDT'] })),
-      decimals: z
-        .number()
-        .check(
-          z.int(),
-          z.gte(0),
-          z.lte(255),
-          z.describe('Number of decimal places the token uses.'),
-          z.meta({ examples: [6] }),
+  export const Asset = OpenApi.component(
+    Schema.describe(
+      z.object({
+        id: schema.ChecksummedAddress.check(
+          z.describe('Checksummed TIP-20 token contract address.'),
+          z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
         ),
-      totalSupply: z
-        .string()
-        .check(
-          z.describe(
-            'Total token supply as a decimal string, already adjusted for token decimals.',
+        name: z
+          .string()
+          .check(z.describe('Human-readable token name.'), z.meta({ examples: ['Tempo USD'] })),
+        symbol: z
+          .string()
+          .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDT'] })),
+        decimals: z
+          .number()
+          .check(
+            z.int(),
+            z.gte(0),
+            z.lte(255),
+            z.describe('Number of decimal places the token uses.'),
+            z.meta({ examples: [6] }),
           ),
-          z.meta({ examples: ['1000000'] }),
-        ),
-    }),
-    'A TIP-20 token in CoinGecko’s GeckoTerminal asset format.',
+        totalSupply: z
+          .string()
+          .check(
+            z.describe(
+              'Total token supply as a decimal string, already adjusted for token decimals.',
+            ),
+            z.meta({ examples: ['1000000'] }),
+          ),
+      }),
+      'A TIP-20 token in CoinGecko’s GeckoTerminal asset format.',
+    ),
+    'CoinGeckoAsset',
   )
 
   /** `GET /:chainId/assets/:address` response. */
-  export const AssetResponse = Schema.describe(
-    z.object({ asset: Asset }),
-    'One TIP-20 token in CoinGecko’s GeckoTerminal asset format.',
+  export const AssetResponse = OpenApi.component(
+    Schema.describe(
+      z.object({ asset: Asset }),
+      'One TIP-20 token in CoinGecko’s GeckoTerminal asset format.',
+    ),
+    'CoinGeckoAssetResponse',
   )
 
   /** A pair-side token (asset plus checksummed address). */
-  export const PairToken = Schema.describe(
-    z.object({
-      address: schema.ChecksummedAddress.check(
-        z.describe('Checksummed TIP-20 token contract address.'),
-        z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
-      ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable token name.'), z.meta({ examples: ['Tempo USD'] })),
-      symbol: z
-        .string()
-        .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDT'] })),
-      decimals: z
-        .number()
-        .check(
-          z.int(),
-          z.gte(0),
-          z.lte(255),
-          z.describe('Number of decimal places the token uses.'),
-          z.meta({ examples: [6] }),
+  export const PairToken = OpenApi.component(
+    Schema.describe(
+      z.object({
+        address: schema.ChecksummedAddress.check(
+          z.describe('Checksummed TIP-20 token contract address.'),
+          z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
         ),
-      totalSupply: z
-        .string()
-        .check(
-          z.describe(
-            'Total token supply as a decimal string, already adjusted for token decimals.',
+        name: z
+          .string()
+          .check(z.describe('Human-readable token name.'), z.meta({ examples: ['Tempo USD'] })),
+        symbol: z
+          .string()
+          .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDT'] })),
+        decimals: z
+          .number()
+          .check(
+            z.int(),
+            z.gte(0),
+            z.lte(255),
+            z.describe('Number of decimal places the token uses.'),
+            z.meta({ examples: [6] }),
           ),
-          z.meta({ examples: ['1000000'] }),
-        ),
-    }),
-    'One token side of a trading pair.',
+        totalSupply: z
+          .string()
+          .check(
+            z.describe(
+              'Total token supply as a decimal string, already adjusted for token decimals.',
+            ),
+            z.meta({ examples: ['1000000'] }),
+          ),
+      }),
+      'One token side of a trading pair.',
+    ),
+    'CoinGeckoPairToken',
   )
 
   /** A GeckoTerminal trading pair. */
-  export const Pair = Schema.describe(
-    z.object({
-      id: Schema.Hash.check(z.describe('32-byte onchain order-book key for this trading pair.')),
-      dexKey: z
-        .string()
-        .check(
-          z.describe('Stable identifier for Tempo’s DEX venue.'),
-          z.meta({ examples: [dexKey] }),
-        ),
-      asset0Id: schema.ChecksummedAddress.check(
-        z.describe('Checksummed address of the base token (`asset0`).'),
-        z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
-      ),
-      asset1Id: schema.ChecksummedAddress.check(
-        z.describe('Checksummed address of the quote token (`asset1`).'),
-        z.meta({ examples: ['0x20C0000000000000000000000000000000000000'] }),
-      ),
-      token0: PairToken,
-      token1: PairToken,
-      reserve0: z
-        .string()
-        .check(
-          z.describe('Best-effort current base-side reserve as a decimal string.'),
-          z.meta({ examples: ['1000000'] }),
+  export const Pair = OpenApi.component(
+    Schema.describe(
+      z.object({
+        id: Schema.Hash.check(z.describe('32-byte onchain order-book key for this trading pair.')),
+        dexKey: z
+          .string()
+          .check(
+            z.describe('Stable identifier for Tempo’s DEX venue.'),
+            z.meta({ examples: [dexKey] }),
+          ),
+        asset0Id: schema.ChecksummedAddress.check(
+          z.describe('Checksummed address of the base token (`asset0`).'),
+          z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
         ),
-      reserve1: z
-        .string()
-        .check(
-          z.describe('Best-effort current quote-side reserve as a decimal string.'),
-          z.meta({ examples: ['1500000'] }),
+        asset1Id: schema.ChecksummedAddress.check(
+          z.describe('Checksummed address of the quote token (`asset1`).'),
+          z.meta({ examples: ['0x20C0000000000000000000000000000000000000'] }),
         ),
-      createdAtBlockNumber: z
-        .optional(
-          z
-            .number()
-            .check(
-              z.int(),
-              z.nonnegative(),
-              z.describe('Block number where the pair was created, when indexed.'),
-            ),
-        )
-        .check(z.meta({ examples: [23456789] })),
-      createdAtBlockTimestamp: z
-        .optional(
-          z
-            .number()
-            .check(
-              z.int(),
-              z.nonnegative(),
-              z.describe('Unix timestamp for when the pair was created, when indexed.'),
-            ),
-        )
-        .check(z.meta({ examples: [1718668800] })),
-      createdAtTxnId: z
-        .optional(
-          z.string().check(z.describe('Transaction hash that created the pair, when indexed.')),
-        )
-        .check(
-          z.meta({
-            examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'],
-          }),
-        ),
-    }),
-    'A Tempo stablecoin DEX trading pair in GeckoTerminal format.',
+        token0: PairToken,
+        token1: PairToken,
+        reserve0: z
+          .string()
+          .check(
+            z.describe('Best-effort current base-side reserve as a decimal string.'),
+            z.meta({ examples: ['1000000'] }),
+          ),
+        reserve1: z
+          .string()
+          .check(
+            z.describe('Best-effort current quote-side reserve as a decimal string.'),
+            z.meta({ examples: ['1500000'] }),
+          ),
+        createdAtBlockNumber: z
+          .optional(
+            z
+              .number()
+              .check(
+                z.int(),
+                z.nonnegative(),
+                z.describe('Block number where the pair was created, when indexed.'),
+              ),
+          )
+          .check(z.meta({ examples: [23456789] })),
+        createdAtBlockTimestamp: z
+          .optional(
+            z
+              .number()
+              .check(
+                z.int(),
+                z.nonnegative(),
+                z.describe('Unix timestamp for when the pair was created, when indexed.'),
+              ),
+          )
+          .check(z.meta({ examples: [1718668800] })),
+        createdAtTxnId: z
+          .optional(
+            z.string().check(z.describe('Transaction hash that created the pair, when indexed.')),
+          )
+          .check(
+            z.meta({
+              examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'],
+            }),
+          ),
+      }),
+      'A Tempo stablecoin DEX trading pair in GeckoTerminal format.',
+    ),
+    'CoinGeckoPair',
   )
 
   /** `GET /:chainId/pairs` response. */
-  export const PairsResponse = Schema.describe(
-    z.object({
-      pairs: z.array(Pair).check(z.describe('Trading pairs ordered by creation block.')),
-    }),
-    'A page of Tempo stablecoin DEX trading pairs.',
+  export const PairsResponse = OpenApi.component(
+    Schema.describe(
+      z.object({
+        pairs: z.array(Pair).check(z.describe('Trading pairs ordered by creation block.')),
+      }),
+      'A page of Tempo stablecoin DEX trading pairs.',
+    ),
+    'CoinGeckoPairsResponse',
   )
 
   /** `GET /:chainId/pairs/:pairId` response. */
-  export const PairResponse = Schema.describe(
-    z.object({ pair: Pair }),
-    'One Tempo stablecoin DEX trading pair.',
+  export const PairResponse = OpenApi.component(
+    Schema.describe(z.object({ pair: Pair }), 'One Tempo stablecoin DEX trading pair.'),
+    'CoinGeckoPairResponse',
   )
 
   /** Path parameters addressing a single pair. */
@@ -371,102 +395,108 @@ export namespace schema {
     .check(z.describe('Block range to scan for swap events, including both endpoints.'))
 
   /** A GeckoTerminal swap event (one per `OrderFilled`). */
-  export const SwapEvent = Schema.describe(
-    z.object({
-      block: Block,
-      eventType: z
-        .literal('swap')
-        .check(
-          z.describe('Event type; always `swap` for this feed.'),
-          z.meta({ examples: ['swap'] }),
-        ),
-      txnId: z.string().check(
-        z.describe('Hash of the transaction that emitted the swap event.'),
-        z.meta({
-          examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'],
-        }),
-      ),
-      txnIndex: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Zero-based position of the transaction within its block.'),
-          z.meta({ examples: [1] }),
-        ),
-      eventIndex: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Zero-based position of this swap within its transaction.'),
-          z.meta({ examples: [0] }),
-        ),
-      maker: schema.ChecksummedAddress.check(
-        z.describe('Checksummed address of the taker, usually the transaction sender.'),
-        z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
-      ),
-      pairId: Schema.Hash.check(z.describe('On-chain order-book key for the trading pair.')),
-      asset0In: z
-        .optional(z.string())
-        .check(
-          z.describe('Base token (`asset0`) amount sent into the swap, when applicable.'),
-          z.meta({ examples: ['1000'] }),
-        ),
-      asset1In: z
-        .optional(z.string())
-        .check(
-          z.describe('Quote token (`asset1`) amount sent into the swap, when applicable.'),
-          z.meta({ examples: ['1500'] }),
-        ),
-      asset0Out: z
-        .optional(z.string())
-        .check(
-          z.describe('Base token (`asset0`) amount received from the swap, when applicable.'),
-          z.meta({ examples: ['1000'] }),
-        ),
-      asset1Out: z
-        .optional(z.string())
-        .check(
-          z.describe('Quote token (`asset1`) amount received from the swap, when applicable.'),
-          z.meta({ examples: ['1500'] }),
+  export const SwapEvent = OpenApi.component(
+    Schema.describe(
+      z.object({
+        block: Block,
+        eventType: z
+          .literal('swap')
+          .check(
+            z.describe('Event type; always `swap` for this feed.'),
+            z.meta({ examples: ['swap'] }),
+          ),
+        txnId: z.string().check(
+          z.describe('Hash of the transaction that emitted the swap event.'),
+          z.meta({
+            examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'],
+          }),
         ),
-      priceNative: z
-        .string()
-        .check(
-          z.describe('Quote-per-base price as a 36-decimal-place string.'),
-          z.meta({ examples: ['1.5'] }),
+        txnIndex: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Zero-based position of the transaction within its block.'),
+            z.meta({ examples: [1] }),
+          ),
+        eventIndex: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Zero-based position of this swap within its transaction.'),
+            z.meta({ examples: [0] }),
+          ),
+        maker: schema.ChecksummedAddress.check(
+          z.describe('Checksummed address of the taker, usually the transaction sender.'),
+          z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
         ),
-      reserves: z
-        .object({
-          asset0: z
-            .string()
-            .check(
-              z.describe('Best-effort current base-token reserve.'),
-              z.meta({ examples: ['1000000'] }),
-            ),
-          asset1: z
-            .string()
-            .check(
-              z.describe('Best-effort current quote-token reserve.'),
-              z.meta({ examples: ['1500000'] }),
-            ),
-        })
-        .check(z.describe('Best-effort current reserves for both sides of the pair.')),
-    }),
-    'A Tempo DEX swap event in GeckoTerminal format.',
+        pairId: Schema.Hash.check(z.describe('On-chain order-book key for the trading pair.')),
+        asset0In: z
+          .optional(z.string())
+          .check(
+            z.describe('Base token (`asset0`) amount sent into the swap, when applicable.'),
+            z.meta({ examples: ['1000'] }),
+          ),
+        asset1In: z
+          .optional(z.string())
+          .check(
+            z.describe('Quote token (`asset1`) amount sent into the swap, when applicable.'),
+            z.meta({ examples: ['1500'] }),
+          ),
+        asset0Out: z
+          .optional(z.string())
+          .check(
+            z.describe('Base token (`asset0`) amount received from the swap, when applicable.'),
+            z.meta({ examples: ['1000'] }),
+          ),
+        asset1Out: z
+          .optional(z.string())
+          .check(
+            z.describe('Quote token (`asset1`) amount received from the swap, when applicable.'),
+            z.meta({ examples: ['1500'] }),
+          ),
+        priceNative: z
+          .string()
+          .check(
+            z.describe('Quote-per-base price as a 36-decimal-place string.'),
+            z.meta({ examples: ['1.5'] }),
+          ),
+        reserves: z
+          .object({
+            asset0: z
+              .string()
+              .check(
+                z.describe('Best-effort current base-token reserve.'),
+                z.meta({ examples: ['1000000'] }),
+              ),
+            asset1: z
+              .string()
+              .check(
+                z.describe('Best-effort current quote-token reserve.'),
+                z.meta({ examples: ['1500000'] }),
+              ),
+          })
+          .check(z.describe('Best-effort current reserves for both sides of the pair.')),
+      }),
+      'A Tempo DEX swap event in GeckoTerminal format.',
+    ),
+    'CoinGeckoSwapEvent',
   )
 
   /** `GET /:chainId/events` response. */
-  export const EventsResponse = Schema.describe(
-    z.object({
-      events: z
-        .array(SwapEvent)
-        .check(
-          z.describe('Swap events in the requested block range, ordered by block and log index.'),
-        ),
-    }),
-    'Tempo DEX swap events for the requested block range.',
+  export const EventsResponse = OpenApi.component(
+    Schema.describe(
+      z.object({
+        events: z
+          .array(SwapEvent)
+          .check(
+            z.describe('Swap events in the requested block range, ordered by block and log index.'),
+          ),
+      }),
+      'Tempo DEX swap events for the requested block range.',
+    ),
+    'CoinGeckoEventsResponse',
   )
 }
 
@@ -497,6 +527,11 @@ export function coingecko() {
           'Returns the latest indexed Tempo block in GeckoTerminal format so DEX data tools know where to start polling.',
         operationId: 'coingeckoLatestBlock',
         responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['chain_id_invalid', 'chain_id_unsupported'] },
+            404: { description: 'No indexed block was found.', codes: ['not_found'] },
+            502: 'The upstream Tempo indexer could not complete the request.',
+          },
           success: {
             description: 'Latest indexed Tempo block.',
             schema: schema.LatestBlockResponse,
@@ -538,10 +573,14 @@ export function coingecko() {
         operationId: 'coingeckoAsset',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: ['address_invalid', 'chain_id_invalid', 'chain_id_unsupported'],
+            },
             404: {
               description: 'No TIP-20 asset was found for that address.',
               codes: ['not_found'],
             },
+            502: 'Tempo RPC could not resolve the requested asset.',
           },
           success: {
             description: 'A TIP-20 token in CoinGecko’s GeckoTerminal asset format.',
@@ -594,7 +633,13 @@ export function coingecko() {
         description: 'Lists Tempo stablecoin DEX trading pairs in GeckoTerminal format.',
         operationId: 'coingeckoPairs',
         responses: OpenApi.responses({
-          errors: { 400: 'The `limit` query parameter is invalid.' },
+          errors: {
+            400: {
+              description: 'The chain id or `limit` query parameter is invalid.',
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+            },
+            502: 'Tempo RPC or the upstream indexer could not complete the request.',
+          },
           success: {
             description: 'Trading pairs in GeckoTerminal format.',
             schema: schema.PairsResponse,
@@ -662,7 +707,11 @@ export function coingecko() {
         operationId: 'coingeckoPair',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'pair_id_invalid'],
+            },
             404: { description: 'No trading pair was found for that id.', codes: ['not_found'] },
+            502: 'Tempo RPC or the upstream indexer could not complete the request.',
           },
           success: {
             description: 'One trading pair in GeckoTerminal format.',
@@ -727,7 +776,14 @@ export function coingecko() {
         description: 'Returns Tempo DEX swap events over a block range in GeckoTerminal format.',
         operationId: 'coingeckoEvents',
         responses: OpenApi.responses({
-          errors: { 400: 'The requested block range is invalid.' },
+          errors: {
+            400: {
+              description: 'The chain id or requested block range is invalid.',
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+            },
+            404: { description: 'No indexed block was found.', codes: ['not_found'] },
+            502: 'The upstream Tempo indexer could not complete the request.',
+          },
           success: {
             description: 'Swap events in the requested block range.',
             schema: schema.EventsResponse,