tapimo 0.14.0 → 0.15.0

package/src/apps/data/routes/fee-amm.ts

@@ -60,49 +60,52 @@ export namespace schema {
    * metadata. Fee AMM mints use this shape; pools require core metadata through
    * `getFeeAmmPools.Token`.
    */
-  export const PoolToken = Schema.describe(
-    z.object({
-      address: Schema.tokenAddress(Tokens.tokenExample.address).check(
-        z.describe('TIP-20 token contract address used by this fee pool.'),
-      ),
-      currency: z
-        .optional(z.string())
-        .check(
-          z.describe('Display currency for the token, when available.'),
-          z.meta({ examples: [Tokens.tokenExample.currency] }),
-        ),
-      decimals: z
-        .optional(z.number().check(z.int(), z.nonnegative()))
-        .check(
-          z.describe('Number of decimal places the token uses.'),
-          z.meta({ examples: [Tokens.tokenExample.decimals] }),
-        ),
-      logoUri: z.optional(z.string()).check(
-        z.describe('URL for the token logo image, when available.'),
-        z.meta({
-          examples: [Tokens.tokenExample.logoUri],
-        }),
-      ),
-      name: z
-        .optional(z.string())
-        .check(
-          z.describe('Human-readable token name.'),
-          z.meta({ examples: [Tokens.tokenExample.name] }),
+  export const PoolToken = OpenApi.component(
+    Schema.describe(
+      z.object({
+        address: Schema.tokenAddress(Tokens.tokenExample.address).check(
+          z.describe('TIP-20 token contract address used by this fee pool.'),
         ),
-      symbol: z
-        .optional(z.string())
-        .check(
-          z.describe('Short token ticker symbol.'),
-          z.meta({ examples: [Tokens.tokenExample.symbol] }),
-        ),
-      verified: z
-        .optional(z.boolean())
-        .check(
-          z.describe('Whether Tempo has verified this token’s metadata.'),
-          z.meta({ examples: [true] }),
+        currency: z
+          .optional(z.string())
+          .check(
+            z.describe('Display currency for the token, when available.'),
+            z.meta({ examples: [Tokens.tokenExample.currency] }),
+          ),
+        decimals: z
+          .optional(z.number().check(z.int(), z.nonnegative()))
+          .check(
+            z.describe('Number of decimal places the token uses.'),
+            z.meta({ examples: [Tokens.tokenExample.decimals] }),
+          ),
+        logoUri: z.optional(z.string()).check(
+          z.describe('URL for the token logo image, when available.'),
+          z.meta({
+            examples: [Tokens.tokenExample.logoUri],
+          }),
         ),
-    }),
-    'A TIP-20 token used by a Fee AMM pool, with metadata when available.',
+        name: z
+          .optional(z.string())
+          .check(
+            z.describe('Human-readable token name.'),
+            z.meta({ examples: [Tokens.tokenExample.name] }),
+          ),
+        symbol: z
+          .optional(z.string())
+          .check(
+            z.describe('Short token ticker symbol.'),
+            z.meta({ examples: [Tokens.tokenExample.symbol] }),
+          ),
+        verified: z
+          .optional(z.boolean())
+          .check(
+            z.describe('Whether Tempo has verified this token’s metadata.'),
+            z.meta({ examples: [true] }),
+          ),
+      }),
+      'A TIP-20 token used by a Fee AMM pool, with metadata when available.',
+    ),
+    'FeeAmmMintToken',
   )
 
   /** Schemas for the getFeeAmmPools operation. */
@@ -133,64 +136,73 @@ export namespace schema {
       .check(...Schema.pageChecks(), z.describe('Query parameters for listing Fee AMM pools.'))
 
     /** A fee-pool token with required RPC metadata and optional curated fields. */
-    export const Token = Schema.describe(
-      Tokens.schema.TokenReference,
-      'A token referenced by one side of a Fee AMM pool.',
+    export const Token = OpenApi.component(
+      Schema.describe(
+        Tokens.schema.TokenReference,
+        'A token referenced by one side of a Fee AMM pool.',
+      ),
+      'FeeAmmPoolToken',
     )
 
     /** A fee AMM pool, aggregated from its `Mint` events. */
-    export const Pool = z
-      .object({
-        createdAt: z.iso
-          .datetime()
-          .check(
-            z.describe('Timestamp when liquidity was first minted into this pool.'),
-            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
-          ),
-        id: Schema.Hash.check(
-          z.describe('Stable resource id for the pool; this is the same value as `poolId`.'),
-        ),
-        lastMintAt: z.iso
-          .datetime()
-          .check(
-            z.describe('Timestamp when liquidity was most recently minted into this pool.'),
-            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
-          ),
-        mintCount: z
-          .number()
-          .check(
-            z.int(),
-            z.nonnegative(),
-            z.describe('Number of liquidity mints into this pool.'),
-            z.meta({ examples: [25] }),
-          ),
-        poolId: Schema.Hash.check(
-          z.describe(
-            'Pool id computed as `keccak256(abi.encode(userToken, validatorToken))`, matching `FeeManager.getPoolId`.',
+    export const Pool = OpenApi.component(
+      z
+        .object({
+          createdAt: z.iso
+            .datetime()
+            .check(
+              z.describe('Timestamp when liquidity was first minted into this pool.'),
+              z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+            ),
+          id: Schema.Hash.check(
+            z.describe('Stable resource id for the pool; this is the same value as `poolId`.'),
           ),
-        ),
-        userAmount: z
-          .optional(Schema.TokenAmount)
-          .check(z.describe('Current user-token reserve. Omitted when the onchain read fails.')),
-        userToken: Token.check(z.describe('Token users pay fees with in this pool.')),
-        validatorAmount: z
-          .optional(Schema.TokenAmount)
-          .check(
-            z.describe('Current validator-token reserve. Omitted when the onchain read fails.'),
+          lastMintAt: z.iso
+            .datetime()
+            .check(
+              z.describe('Timestamp when liquidity was most recently minted into this pool.'),
+              z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+            ),
+          mintCount: z
+            .number()
+            .check(
+              z.int(),
+              z.nonnegative(),
+              z.describe('Number of liquidity mints into this pool.'),
+              z.meta({ examples: [25] }),
+            ),
+          poolId: Schema.Hash.check(
+            z.describe(
+              'Pool id computed as `keccak256(abi.encode(userToken, validatorToken))`, matching `FeeManager.getPoolId`.',
+            ),
           ),
-        validatorToken: Token.check(z.describe('Token validators receive from this pool.')),
-      })
-      .check(z.describe('A Fee AMM pool discovered from its onchain `Mint` events.'))
+          userAmount: z
+            .optional(Schema.TokenAmount)
+            .check(z.describe('Current user-token reserve. Omitted when the onchain read fails.')),
+          userToken: Token,
+          validatorAmount: z
+            .optional(Schema.TokenAmount)
+            .check(
+              z.describe('Current validator-token reserve. Omitted when the onchain read fails.'),
+            ),
+          validatorToken: Token,
+        })
+        .check(z.describe('A Fee AMM pool discovered from its onchain `Mint` events.')),
+      'FeeAmmPool',
+    )
 
     /** Page of fee pools, ordered by mint count (most active first). */
-    export const Response = z
-      .object({
-        data: z
-          .array(Pool)
-          .check(z.describe('Fee AMM pools ordered by mint count, most active first.')),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of Fee AMM pools ordered by mint count, most active first.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z
+            .array(Pool)
+            .check(z.describe('Fee AMM pools ordered by mint count, most active first.')),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of Fee AMM pools ordered by mint count, most active first.')),
+      'FeeAmmPoolList',
+    )
   }
 
   /** Schemas for the getFeeAmmMints operation. */
@@ -217,79 +229,88 @@ export namespace schema {
       )
 
     /** A single liquidity mint into a fee pool. */
-    export const Mint = z
-      .object({
-        amountUserToken: z
-          .optional(Schema.DecimalString)
-          .check(
-            z.describe(
-              'Amount of the user-side token deposited, in base units. Only present on legacy-signature mints.',
+    export const Mint = OpenApi.component(
+      z
+        .object({
+          amountUserToken: z
+            .optional(Schema.DecimalString)
+            .check(
+              z.describe(
+                'Amount of the user-side token deposited, in base units. Only present on legacy-signature mints.',
+              ),
             ),
+          amountValidatorToken: Schema.DecimalString.check(
+            z.describe('Amount of the validator-side token deposited, in base units.'),
           ),
-        amountValidatorToken: Schema.DecimalString.check(
-          z.describe('Amount of the validator-side token deposited, in base units.'),
-        ),
-        blockNumber: z
-          .number()
-          .check(
-            z.int(),
-            z.nonnegative(),
-            z.describe('Block number where the mint occurred.'),
-            z.meta({ examples: [23456789] }),
-          ),
-        id: z.string().check(
-          z.describe(
-            'Stable mint id built from the transaction hash and log index (`${transactionHash}-${logIndex}`).',
-          ),
-          z.meta({
-            examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-0'],
-          }),
-        ),
-        liquidity: Schema.DecimalString.check(
-          z.describe('Amount of pool liquidity minted, as an integer string.'),
-        ),
-        logIndex: z
-          .number()
-          .check(
-            z.int(),
-            z.nonnegative(),
-            z.describe('Log index of this mint within the block.'),
-            z.meta({ examples: [0] }),
-          ),
-        minter: Schema.Address.check(z.describe('Address that deposited tokens into the pool.')),
-        recipient: z
-          .optional(Schema.Address)
-          .check(
+          blockNumber: z
+            .number()
+            .check(
+              z.int(),
+              z.nonnegative(),
+              z.describe('Block number where the mint occurred.'),
+              z.meta({ examples: [23456789] }),
+            ),
+          id: z.string().check(
             z.describe(
-              'Address that received the minted liquidity. Only present on current-signature mints.',
+              'Stable mint id built from the transaction hash and log index (`${transactionHash}-${logIndex}`).',
             ),
+            z.meta({
+              examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-0'],
+            }),
           ),
-        timestamp: z.iso
-          .datetime()
-          .check(
-            z.describe('Block timestamp when the mint occurred.'),
-            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+          liquidity: Schema.DecimalString.check(
+            z.describe('Amount of pool liquidity minted, as an integer string.'),
           ),
-        transactionHash: Schema.Hash.check(
-          z.describe('Hash of the transaction that emitted this mint.'),
-        ),
-        userToken: PoolToken.check(z.describe('Token users pay fees with in this pool.')),
-        validatorToken: PoolToken.check(z.describe('Token validators receive from this pool.')),
-      })
-      .check(z.describe('One liquidity mint into a Fee AMM pool.'))
+          logIndex: z
+            .number()
+            .check(
+              z.int(),
+              z.nonnegative(),
+              z.describe('Log index of this mint within the block.'),
+              z.meta({ examples: [0] }),
+            ),
+          minter: Schema.Address.check(z.describe('Address that deposited tokens into the pool.')),
+          recipient: z
+            .optional(Schema.Address)
+            .check(
+              z.describe(
+                'Address that received the minted liquidity. Only present on current-signature mints.',
+              ),
+            ),
+          timestamp: z.iso
+            .datetime()
+            .check(
+              z.describe('Block timestamp when the mint occurred.'),
+              z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+            ),
+          transactionHash: Schema.Hash.check(
+            z.describe('Hash of the transaction that emitted this mint.'),
+          ),
+          userToken: PoolToken,
+          validatorToken: PoolToken,
+        })
+        .check(z.describe('One liquidity mint into a Fee AMM pool.')),
+      'FeeAmmMint',
+    )
+
+    /** Response metadata requested through `include`, such as capped counts. */
+    export const Meta = OpenApi.component(Schema.CountMeta, 'FeeAmmMintListMeta')
 
     /** Page of fee pool mints, ordered by block then log index. */
-    export const Response = z
-      .object({
-        data: z.array(Mint).check(z.describe('Liquidity mints returned on this page.')),
-        meta: z
-          .optional(Schema.CountMeta)
-          .check(
-            z.describe('Response-wide metadata requested with `include`, such as `totalCount`.'),
-          ),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of Fee AMM liquidity mints.'))
+    export const Response = OpenApi.component(
+      z
+        .object({
+          data: z.array(Mint).check(z.describe('Liquidity mints returned on this page.')),
+          meta: z
+            .optional(Meta)
+            .check(
+              z.describe('Response-wide metadata requested with `include`, such as `totalCount`.'),
+            ),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of Fee AMM liquidity mints.')),
+      'FeeAmmMintList',
+    )
   }
 }
 
@@ -305,10 +326,15 @@ export function feeAmm() {
       }),
       OpenApi.describeRoute({
         description:
-          'Lists Fee AMM pools, most active first, so you can see which stablecoin fee conversions have the most liquidity activity.',
+          'Lists Fee AMM pools by mint activity, showing which stablecoin fee conversions have the most liquidity activity.',
         operationId: 'getFeeAmmPools',
         responses: OpenApi.responses({
-          errors: { 502: 'Tempo RPC or the upstream indexer could not complete the request.' },
+          errors: {
+            400: {
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+            },
+            502: 'Tempo RPC or the upstream indexer could not complete the request.',
+          },
           success: {
             description: 'List of Fee AMM pools.',
             schema: schema.getFeeAmmPools.Response,
@@ -425,7 +451,12 @@ export function feeAmm() {
         description: 'Lists liquidity mints into Fee AMM pools.',
         operationId: 'getFeeAmmMints',
         responses: OpenApi.responses({
-          errors: { 502: 'The upstream Tempo indexer could not complete the request.' },
+          errors: {
+            400: {
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+            },
+            502: 'The upstream Tempo indexer could not complete the request.',
+          },
           success: {
             description: 'Page of Fee AMM liquidity mints.',
             schema: schema.getFeeAmmMints.Response,