tapimo 0.6.0 → 0.7.0

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

@@ -28,10 +28,16 @@ describe.skip('GET /fee-amm/pools', () => {
     expect('nextCursor' in body).toBe(true)
     expect('meta' in body).toBe(false)
 
-    // Stable item shape (sorted keys of the first pool).
-    expect(Object.keys(body.data[0]!).sort()).toMatchInlineSnapshot(`
+    // Stable required shape; reserve amounts remain best-effort.
+    const {
+      userAmount: _userAmount,
+      validatorAmount: _validatorAmount,
+      ...poolShape
+    } = body.data[0]!
+    expect(Object.keys(poolShape).sort()).toMatchInlineSnapshot(`
       [
         "createdAt",
+        "id",
         "lastMintAt",
         "mintCount",
         "poolId",
@@ -40,13 +46,16 @@ describe.skip('GET /fee-amm/pools', () => {
       ]
     `)
 
-    // Every pool: valid ISO timestamps with first mint at or before the most
-    // recent one, and each side's reserve riding on its token reference —
-    // either absent (failed read) or a base-unit decimal `amount` with a
-    // `formatted` decimal form.
-    const validReserve = (token: { amount?: string | undefined; formatted?: string | undefined }) =>
-      (token.amount === undefined && token.formatted === undefined) ||
-      (/^\d+$/.test(token.amount ?? '') && /^\d+(\.\d+)?$/.test(token.formatted ?? ''))
+    const validAmount = (
+      amount:
+        | { baseUnits: string; currency: string; decimals: number; formatted: string }
+        | undefined,
+    ) =>
+      amount === undefined ||
+      (/^\d+$/.test(amount.baseUnits) &&
+        amount.currency.length > 0 &&
+        Number.isInteger(amount.decimals) &&
+        /^\d+(\.\d+)?$/.test(amount.formatted))
     expect(
       body.data.every(
         (pool) =>
@@ -54,8 +63,12 @@ describe.skip('GET /fee-amm/pools', () => {
           !Number.isNaN(Date.parse(pool.lastMintAt)) &&
           Date.parse(pool.createdAt) <= Date.parse(pool.lastMintAt) &&
           pool.mintCount > 0 &&
-          validReserve(pool.userToken) &&
-          validReserve(pool.validatorToken),
+          pool.userToken.currency.length > 0 &&
+          pool.userToken.symbol.length > 0 &&
+          pool.validatorToken.currency.length > 0 &&
+          pool.validatorToken.symbol.length > 0 &&
+          validAmount(pool.userAmount) &&
+          validAmount(pool.validatorAmount),
       ),
     ).toBe(true)
     // Presentation order: most active first (by mint count).
@@ -130,7 +143,7 @@ describe.skip('GET /fee-amm/pools', () => {
     expect(pageTwo.data[0]!.mintCount).toBeLessThanOrEqual(pageOne.data.at(-1)!.mintCount)
   })
 
-  test('omits token metadata by default and embeds it via include=token', async () => {
+  test('returns core token metadata and opts into curated fields', async () => {
     const client = TestApp.client()
     const baseResponse = await client.v1['fee-amm'].pools.$get(
       { query: { limit: '5' } },
@@ -140,31 +153,33 @@ describe.skip('GET /fee-amm/pools', () => {
 
     expect(baseResponse.status).toBe(200)
     expect(base.data.length).toBeGreaterThan(0)
-    // The base page resolves no token metadata: each side carries just its
-    // `address` plus its (best-effort) reserve, never `symbol`/`decimals`/etc.
     expect(
       base.data.every(
         (pool) =>
-          pool.userToken.symbol === undefined &&
-          pool.userToken.decimals === undefined &&
-          pool.validatorToken.symbol === undefined &&
-          pool.validatorToken.decimals === undefined,
+          pool.userToken.symbol.length > 0 &&
+          Number.isInteger(pool.userToken.decimals) &&
+          pool.userToken.logoUri === undefined &&
+          pool.userToken.verified === undefined &&
+          pool.validatorToken.symbol.length > 0 &&
+          Number.isInteger(pool.validatorToken.decimals) &&
+          pool.validatorToken.logoUri === undefined &&
+          pool.validatorToken.verified === undefined,
       ),
     ).toBe(true)
 
     const includeResponse = await client.v1['fee-amm'].pools.$get(
-      { query: { include: 'token', limit: '5' } },
+      { query: { include: 'token.logoUri,token.verified', limit: '5' } },
       TestApp.auth,
     )
     const included = await TestApp.json(includeResponse, FeeAmm.schema.getFeeAmmPools.Response)
 
     expect(includeResponse.status).toBe(200)
-    // The same pages line up, and `include=token` resolves metadata for at
-    // least one side (verified tokens always carry `symbol`/`decimals`).
     expect(included.data.map((pool) => pool.poolId)).toEqual(base.data.map((pool) => pool.poolId))
     expect(
-      included.data.some(
-        (pool) => pool.userToken.symbol !== undefined || pool.validatorToken.symbol !== undefined,
+      included.data.every(
+        (pool) =>
+          typeof pool.userToken.verified === 'boolean' &&
+          typeof pool.validatorToken.verified === 'boolean',
       ),
     ).toBe(true)
   })
@@ -187,6 +202,15 @@ describe.skip('GET /fee-amm/pools', () => {
   })
 })
 
+describe('GET /fee-amm/pools query', () => {
+  test('rejects the legacy token include', async () => {
+    const response = await TestApp.create().request('/v1/fee-amm/pools?include=token', {
+      headers: TestApp.auth.headers,
+    })
+    expect(response.status).toBe(400)
+  })
+})
+
 describe('GET /fee-amm/mints', () => {
   test('returns a decoded head page and walks the cursor to a disjoint page', async () => {
     const client = TestApp.client()

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

@@ -1,5 +1,5 @@
 import { Hono, type Context } from 'hono'
-import { AbiEvent, AbiParameters, Hash, type Hex, Value as core_Value } from 'ox'
+import { AbiEvent, AbiParameters, Hash, type Hex } from 'ox'
 import { Abis, Addresses } from 'viem/tempo'
 import * as z from 'zod/mini'
 
@@ -48,11 +48,8 @@ const legacyMintTopic = AbiEvent.getSelector(
 export namespace schema {
   /**
    * A token referenced by a fee pool: its contract address plus best-effort
-   * metadata. Mirrors the transfer feed's `sourceToken` technique: `address`
-   * is always present; the metadata fields spread in only when resolution
-   * succeeds, so a token whose metadata is unavailable keeps just the bare
-   * reference. The pools listing extends this shape with the side's reserve
-   * (`getFeeAmmPools.Token`).
+   * metadata. Fee AMM mints use this shape; pools require core metadata through
+   * `getFeeAmmPools.Token`.
    */
   export const PoolToken = Schema.describe(
     z.object({
@@ -94,21 +91,18 @@ export namespace schema {
 
   /** Schemas for the getFeeAmmPools operation. */
   export namespace getFeeAmmPools {
-    /** Optional related resources that callers opt into via `include`. */
+    /** Optional curated token fields that callers opt into via `include`. */
     export const Include = z
-      .enum(['token'])
-      .check(z.describe('Optional related data you can request with `include`.'))
+      .enum(['token.logoUri', 'token.verified'])
+      .check(z.describe('Additional token fields to include in the pool response.'))
 
     /**
-     * Parses a comma-separated `include` query value into a list of optional
-     * resources to embed. Token metadata resolution is one extra (batched)
-     * `token.getMetadata` round trip, so it runs only when `include=token` is
-     * requested; the base page returns each side's bare `address` plus its
-     * reserve and skips the lookup entirely.
+     * Parses comma-separated curated token fields. Core token metadata is
+     * always present; callers opt into logo and verification fields.
      */
     export const includeQuery = Schema.includeQuery(
       Include,
-      'Comma-separated related resources to include, such as `token` metadata.',
+      'Comma-separated token fields to include, such as `token.logoUri,token.verified`.',
     )
 
     /** Query parameters for the fee pool list request. */
@@ -122,31 +116,10 @@ export namespace schema {
       })
       .check(...Schema.pageChecks(), z.describe('Query parameters for listing Fee AMM pools.'))
 
-    /**
-     * One side of a fee pool: the token reference carrying the side's current
-     * on-chain reserve. `amount`/`formatted` come from `FeeManager.getPool`
-     * and are absent when the read fails (best-effort, like the metadata
-     * fields).
-     */
+    /** A fee-pool token with required RPC metadata and optional curated fields. */
     export const Token = Schema.describe(
-      z.extend(PoolToken, {
-        amount: z
-          .optional(Schema.DecimalString)
-          .check(
-            z.describe(
-              'Current onchain reserve for this token, in base units, from `FeeManager.getPool`. Omitted if the read fails.',
-            ),
-          ),
-        formatted: z
-          .optional(z.string())
-          .check(
-            z.describe(
-              'Reserve as a human-readable decimal string using the token’s `decimals`. Omitted if the read fails.',
-            ),
-            z.meta({ examples: ['1.5'] }),
-          ),
-      }),
-      'One token side of a Fee AMM pool, including its current onchain reserve when available.',
+      Tokens.schema.TokenReference,
+      'A token referenced by one side of a Fee AMM pool.',
     )
 
     /** A fee AMM pool, aggregated from its `Mint` events. */
@@ -180,16 +153,16 @@ export namespace schema {
             'Pool id computed as `keccak256(abi.encode(userToken, validatorToken))`, matching `FeeManager.getPoolId`.',
           ),
         ),
-        userToken: Token.check(
-          z.describe(
-            'Token users pay fees with in this pool, including its current reserve when available.',
-          ),
-        ),
-        validatorToken: Token.check(
-          z.describe(
-            'Token validators receive from this pool, including its current reserve when available.',
+        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.'),
           ),
-        ),
+        validatorToken: Token.check(z.describe('Token validators receive from this pool.')),
       })
       .check(z.describe('A Fee AMM pool discovered from its onchain `Mint` events.'))
 
@@ -319,7 +292,7 @@ export function feeAmm() {
           'Lists Fee AMM pools, most active first, so you can see which stablecoin fee conversions have the most liquidity activity.',
         operationId: 'getFeeAmmPools',
         responses: OpenApi.responses({
-          errors: { 502: 'The upstream Tempo indexer could not complete the request.' },
+          errors: { 502: 'Tempo RPC or the upstream indexer could not complete the request.' },
           success: {
             description: 'List of Fee AMM pools.',
             schema: schema.getFeeAmmPools.Response,
@@ -330,7 +303,7 @@ export function feeAmm() {
       }),
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
-        name: 'tempo-api:fee-amm:v1',
+        name: 'tempo-api:fee-amm-pools:v2',
         key: (c) => Cache.urlKey(c, schema.getFeeAmmPools.Query),
       }),
       async (c) => {
@@ -353,57 +326,63 @@ export function feeAmm() {
           })
           const pools = page.data
 
-          // Reserves are one `getPool` eth_call per pool; viem auto-batches
-          // the concurrent calls into a single deployless multicall round
-          // trip (see `internal/Viem.ts`).
-          const reserves = await Timing.time(c, 'fee_amm_reserves', () =>
-            Promise.all(
-              pools.map((pool) =>
-                getPoolReserves(c, {
-                  chainId,
-                  userToken: pool.userToken,
-                  validatorToken: pool.validatorToken,
-                }),
+          // Reserves and token metadata are independent batched RPC reads.
+          const [reserves, tokensByAddress] = await Promise.all([
+            Timing.time(c, 'fee_amm_reserves', () =>
+              Promise.all(
+                pools.map((pool) =>
+                  getPoolReserves(c, {
+                    chainId,
+                    userToken: pool.userToken,
+                    validatorToken: pool.validatorToken,
+                  }),
+                ),
               ),
             ),
-          )
+            resolveTokenMap(c, {
+              addresses: Array.from(
+                new Set(pools.flatMap((pool) => [pool.userToken, pool.validatorToken])),
+              ),
+              chainId,
+              include: query.include,
+            }),
+          ])
 
-          // Token metadata is one extra (batched) `token.getMetadata` round
-          // trip, opt-in via `include=token`. Without it each side carries
-          // just its `address` and reserve; reserves still format via the
-          // `reserve` helper's TIP-20 (6-decimal) fallback.
-          const tokensByAddress = query.include.includes('token')
-            ? await resolveTokenMap(c, {
-                addresses: Array.from(
-                  new Set(pools.flatMap((pool) => [pool.userToken, pool.validatorToken])),
-                ),
-                chainId,
-              })
-            : undefined
+          const token = (address: z.output<typeof Schema.Address>) => {
+            const metadata = tokensByAddress.get(address)
+            if (!metadata) throw new Error(`Token metadata unavailable for ${address}`)
+            return {
+              address,
+              currency: metadata.currency,
+              decimals: metadata.decimals,
+              ...(query.include.includes('token.logoUri') && metadata.logoUri !== undefined
+                ? { logoUri: metadata.logoUri }
+                : {}),
+              name: metadata.name,
+              symbol: metadata.symbol,
+              ...(query.include.includes('token.verified') && metadata.verified !== undefined
+                ? { verified: metadata.verified }
+                : {}),
+            }
+          }
 
           const data = pools.map((pool, index) => {
             const id = poolId(pool.userToken, pool.validatorToken)
-            const userToken = { address: pool.userToken, ...tokensByAddress?.get(pool.userToken) }
-            const validatorToken = {
-              address: pool.validatorToken,
-              ...tokensByAddress?.get(pool.validatorToken),
-            }
-            // Each side's reserve rides on its token reference (like the
-            // metadata fields): absent when the `getPool` read failed.
+            const userToken = token(pool.userToken)
+            const validatorToken = token(pool.validatorToken)
             return {
               createdAt: pool.createdAt,
               id,
               lastMintAt: pool.lastMintAt,
               mintCount: pool.mintCount,
               poolId: id,
-              userToken: {
-                ...userToken,
-                ...reserve(reserves[index]?.userToken, userToken.decimals),
-              },
-              validatorToken: {
-                ...validatorToken,
-                ...reserve(reserves[index]?.validatorToken, validatorToken.decimals),
-              },
+              userAmount: reserve({ amount: reserves[index]?.userToken, token: userToken }),
+              userToken,
+              validatorAmount: reserve({
+                amount: reserves[index]?.validatorToken,
+                token: validatorToken,
+              }),
+              validatorToken,
             }
           })
 
@@ -1030,38 +1009,31 @@ declare namespace decodeMint {
 }
 
 /**
- * Resolves best-effort metadata for the given token addresses, sharing one
- * verified-token snapshot across the lookups. Mirrors the transfer feed's
- * `sourceToken` enrichment: a token whose metadata is unavailable maps to
- * undefined, so call sites spreading the result keep just the bare `address`
- * (the `PoolToken` shape).
- *
- * Unlike the full token resource, this resolves only the on-chain metadata
- * (one `token.getMetadata` read per token, auto-batched into a single
- * multicall) plus the in-memory verified snapshot. It deliberately skips the
- * curated R2 logo lookup (`getTokenLogo`), which is an un-batched storage read
- * per token and the dominant cost of the pools/mints listings; `logoUri`
- * therefore falls back to the verified entry's curated URL or the precompile's
- * on-chain `logoURI`, both already in hand.
+ * Resolves RPC metadata and selected curated fields. Logo enrichment uses cached verification data or onchain metadata, avoiding one R2 read per token.
  */
 async function resolveTokenMap(c: Context<App.Environment>, options: resolveTokenMap.Options) {
   const { addresses, chainId } = options
-  const snapshot = await VerifiedTokens.snapshot(c, chainId)
+  const includeLogoUri = options.include?.includes('token.logoUri') ?? true
+  const includeVerified = options.include?.includes('token.verified') ?? true
+  const snapshot =
+    includeLogoUri || includeVerified
+      ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+      : undefined
   const resolved = await Timing.time(c, 'tokens', () =>
     Promise.all(
       addresses.map((token) =>
         Tokens.getTokenMetadata(c, { address: token, chainId })
           .then((metadata) => {
-            const verified = snapshot.byAddress.get(token)
+            const verified = snapshot?.byAddress.get(token)
             return [
               token,
               {
                 currency: metadata.currency,
                 decimals: metadata.decimals,
-                logoUri: verified?.logoUri ?? metadata.logoUri,
+                logoUri: includeLogoUri ? (verified?.logoUri ?? metadata.logoUri) : undefined,
                 name: metadata.name,
                 symbol: metadata.symbol,
-                verified: snapshot.byAddress.has(token),
+                verified: includeVerified ? snapshot?.byAddress.has(token) : undefined,
               },
             ] as const
           })
@@ -1079,6 +1051,8 @@ declare namespace resolveTokenMap {
     addresses: readonly z.output<typeof Schema.Address>[]
     /** Tempo chain id. */
     chainId: z.output<typeof Schema.ChainId>
+    /** Curated token fields to return; omitted to preserve mint enrichment. */
+    include?: readonly z.output<typeof schema.getFeeAmmPools.Include>[] | undefined
   }
 }
 
@@ -1095,19 +1069,24 @@ function poolId(
   )
 }
 
-/**
- * Shapes one side's on-chain reserve for spreading into its token reference:
- * the base-unit `amount` plus its `formatted` decimal form. `decimals` comes
- * from the side's resolved token metadata; an unresolvable token falls back
- * to 6, the fixed TIP-20 precision, so the reserve still formats. A missing
- * amount (failed `getPool` read) yields undefined, leaving both fields absent.
- */
-function reserve(
-  amount: string | undefined,
-  decimals: number | undefined,
-): { amount: string; formatted: string } | undefined {
-  if (amount === undefined) return undefined
-  return { amount, formatted: core_Value.format(BigInt(amount), decimals ?? 6) }
+/** Builds a self-contained reserve amount after a successful onchain read. */
+function reserve(options: reserve.Options) {
+  if (options.amount === undefined) return undefined
+  return Value.tokenAmount({
+    baseUnits: options.amount,
+    currency: options.token.currency,
+    decimals: options.token.decimals,
+  })
+}
+
+declare namespace reserve {
+  /** Inputs for formatting one side of a Fee AMM pool reserve. */
+  type Options = {
+    /** Base-unit reserve returned by `FeeManager.getPool`. */
+    amount: string | undefined
+    /** Token metadata used to describe and format the reserve. */
+    token: Pick<z.output<typeof Tokens.schema.TokenReference>, 'currency' | 'decimals'>
+  }
 }
 
 /** Left-pads a 20-byte address to its 32-byte log-topic form. */

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

@@ -6,6 +6,16 @@ import * as TestApp from '../../../../test/App.js'
 import * as Funding from './funding.js'
 
 describe('GET /funding/quotes', () => {
+  test('publishes alphabetically ordered quote example fields', async () => {
+    const app = TestApp.create({ auth: false })
+    const spec = await (await app.request('/openapi.json')).json()
+    const operation = spec.paths['/v1/funding/quotes'].get
+    const response = operation.responses['200'].content['application/json']
+    const fields = Object.keys(response.example.data[0])
+
+    expect(fields).toEqual([...fields].sort())
+  })
+
   test('returns successful live quotes with output amounts', async () => {
     const app = TestApp.create({ funding: { adapters: { relay: relayAdapter() } } })
     const response = await app.request(quoteUrl(), { headers: TestApp.auth.headers })
@@ -15,16 +25,26 @@ describe('GET /funding/quotes', () => {
 
     expect(body.data).toHaveLength(1)
     expect(body.data[0]).toMatchObject({
+      destinationAmount: {
+        baseUnits: '990000',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '0.99',
+      },
+      destinationAmountMin: {
+        baseUnits: '980000',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '0.98',
+      },
       id: 'base-usdc-tempo-usdce-relay',
       provider: { id: 'relay' },
       quality: { liquiditySource: 'providerQuote', tier: 'liquid' },
-      quote: {
-        inputAmount: '1000000',
-        outputAmount: '990000',
-        outputAmountFormatted: '0.99',
-      },
-      sourceAmount: { amount: '1000000', formatted: '1' },
+      quote: { sampledAt: '2026-01-01T00:00:00Z' },
+      sourceAmount: { baseUnits: '1000000', currency: 'USD', decimals: 6, formatted: '1' },
     })
+    expect(body.data[0]?.sourceToken).not.toHaveProperty('amount')
+    expect(body.data[0]?.destinationToken).not.toHaveProperty('amount')
   })
 
   test('queries only the requested provider', async () => {
@@ -342,6 +362,9 @@ describe('GET /funding/chains', () => {
     expect(body.data.flatMap((chain) => chain.tokens.map((token) => token.symbol))).toEqual(
       expect.arrayContaining(['USDC', 'USDT']),
     )
+    expect(
+      body.data.flatMap((chain) => chain.tokens).every((token) => token.currency === 'USD'),
+    ).toBe(true)
   })
 })
 
@@ -424,7 +447,6 @@ function relayAdapter(onProbe: () => void = () => {}): FundingQuotes.ProviderAda
       return {
         minimumOutputAmount: '980000',
         outputAmount: '990000',
-        outputAmountFormatted: '0.99',
         quality: {
           estimatedSeconds: 4,
           liquiditySource: 'providerQuote',
@@ -448,7 +470,6 @@ function acrossAdapter(onProbe: () => void = () => {}): FundingQuotes.ProviderAd
         expiresAt: '2026-01-01T00:01:00Z',
         minimumOutputAmount: '988000',
         outputAmount: '990000',
-        outputAmountFormatted: '0.99',
         quality: {
           estimatedSeconds: 2,
           liquiditySource: 'providerQuote',