tapimo 0.5.2 → 0.6.0

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

@@ -1,11 +1,62 @@
 import type * as z from 'zod/mini'
-import { Schema } from 'tapimo'
+import { Value as core_Value } from 'ox'
+import { Db, Schema } from 'tapimo'
+import { FxOracle } from 'tapimo/apps'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
 import * as Transfers from './transfers.js'
 
+// Deterministic EUR-based rate set so conversion math is exact in assertions.
+const fixed = FxOracle.from({
+  name: 'fixed',
+  rates: async () => ({ asOf: '2026-01-01', base: 'EUR', rates: { AUD: '1.6', USD: '1.0' } }),
+})
+
 describe('GET /transfers', () => {
+  test('degrades unavailable verification data to null valuations', async () => {
+    const db = () =>
+      Db.postgres({
+        connectionString: 'postgresql://postgres:postgres@127.0.0.1:1/none',
+      })
+    const client = TestApp.client({ db, fx: { oracle: fixed } })
+
+    const response = await client.v1.transfers.$get(
+      { query: { limit: '5', token: TestApp.tokenWithHolders } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transfers.schema.getTransfers.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.data.length).toBeGreaterThan(0)
+    for (const entry of body.data) expect(entry.sourceToken.valuation).toBeNull()
+
+    const emptyResponse = await client.v1.transfers.$get(
+      { query: { limit: '5', token: `0x${'11'.repeat(20)}` } },
+      TestApp.auth,
+    )
+    const empty = await TestApp.json(emptyResponse, Transfers.schema.getTransfers.Response)
+    expect(emptyResponse.status).toBe(200)
+    expect(empty.data).toMatchInlineSnapshot(`[]`)
+    expect(emptyResponse.headers.get('server-timing')?.includes('verified_tokens;dur=')).not.toBe(
+      true,
+    )
+
+    const unsupportedResponse = await client.v1.transfers.$get(
+      {
+        query: {
+          denomination: 'JPY',
+          limit: '5',
+          token: TestApp.tokenWithHolders,
+        },
+      },
+      TestApp.auth,
+    )
+    const unsupported = await TestApp.json(unsupportedResponse, Schema.ErrorResponse)
+    expect(unsupportedResponse.status).toBe(400)
+    expect(unsupported.error.code).toBe('query_invalid')
+  })
+
   test('returns an unscoped transfer page, embedding tokens on demand', async () => {
     const client = TestApp.client()
     const baseResponse = await client.v1.transfers.$get({ query: { limit: '5' } }, TestApp.auth)
@@ -147,6 +198,9 @@ describe('GET /transfers', () => {
     const second = await TestApp.json(secondResponse, Transfers.schema.getTransfers.Response)
 
     expect(secondResponse.status).toBe(200)
+    expect(secondResponse.headers.get('cache-control')).toMatchInlineSnapshot(
+      `"private, max-age=60, stale-while-revalidate=300"`,
+    )
     expect(second.data.length).toBeGreaterThan(0)
     // Each row's identity on the unscoped feed is `(blockNumber, txHash,
     // sourceToken, sender, recipient, amount)` — a single transaction can
@@ -285,7 +339,7 @@ describe('GET /transfers', () => {
     expect(Number.isInteger(body.meta?.totalCount)).toBe(true)
     expect(body.meta!.totalCount).toBeGreaterThanOrEqual(body.data.length)
     expect(body.meta!.totalCount).toBeLessThanOrEqual(Schema.countCap)
-    expect(body.meta!.totalCountCapped).toBe(body.meta!.totalCount >= Schema.countCap)
+    expect(body.meta!.totalCountCapped).toBe(body.meta!.totalCount! >= Schema.countCap)
   })
 
   test('embeds a capped token-scoped total count on demand', async () => {
@@ -309,7 +363,7 @@ describe('GET /transfers', () => {
     expect(typeof body.meta?.totalCountCapped).toBe('boolean')
     // The count never exceeds the cap; `totalCountCapped` is set iff the cap was hit.
     expect(body.meta!.totalCount).toBeLessThanOrEqual(Schema.countCap)
-    expect(body.meta!.totalCountCapped).toBe(body.meta!.totalCount >= Schema.countCap)
+    expect(body.meta!.totalCountCapped).toBe(body.meta!.totalCount! >= Schema.countCap)
 
     // Without `include=totalCount`, the same page omits `meta` entirely and
     // does not run the count query.
@@ -319,7 +373,10 @@ describe('GET /transfers', () => {
     )
     const bare = await TestApp.json(bareResponse, Transfers.schema.getTransfers.Response)
     expect(bareResponse.status).toBe(200)
-    expect(bare.meta).toBeUndefined()
+    // Without the include, counts are omitted (`meta` carries at most rate
+    // provenance).
+    expect(bare.meta?.totalCount).toBeUndefined()
+    expect(bare.meta?.totalCountCapped).toBeUndefined()
     expect(bareResponse.headers.get('server-timing')?.includes('transfers_count;dur=')).toBe(false)
   })
 
@@ -422,6 +479,91 @@ describe('GET /transfers', () => {
     },
   )
 
+  test('values verified transfer legs in the default denomination', async () => {
+    const db = TestApp.database()
+    await TestApp.verifiedSeed(db, Runtime.get().chainId)
+    const client = TestApp.client({ db })
+
+    // pathUSD is curated USD, so its legs value at identity with no rates.
+    const response = await client.v1.transfers.$get(
+      { query: { limit: '5', token: TestApp.tokenWithHolders } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transfers.schema.getTransfers.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.data.length).toBeGreaterThan(0)
+    for (const entry of body.data)
+      expect(entry.sourceToken.valuation).toEqual({
+        amount: core_Value.format(BigInt(entry.sourceToken.amount), 6),
+        currency: 'USD',
+      })
+    expect(body.meta?.pricing).toBeUndefined()
+  })
+
+  test('values transfer legs in a requested denomination', async () => {
+    const db = TestApp.database()
+    await TestApp.verifiedSeed(db, Runtime.get().chainId)
+    const client = TestApp.client({ db, fx: { oracle: fixed } })
+
+    // Denominations are case-insensitive.
+    const response = await client.v1.transfers.$get(
+      { query: { denomination: 'aud', limit: '5', token: TestApp.tokenWithHolders } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Transfers.schema.getTransfers.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.data.length).toBeGreaterThan(0)
+    // USD -> AUD at the fixed 1.6 cross rate, floored to 6 dp.
+    for (const entry of body.data)
+      expect(entry.sourceToken.valuation).toEqual({
+        amount: core_Value.format((BigInt(entry.sourceToken.amount) * 16n) / 10n, 6),
+        currency: 'AUD',
+      })
+    expect(body.meta?.pricing).toMatchInlineSnapshot(`
+      {
+        "asOf": "2026-01-01",
+        "basis": "nominal",
+        "source": "fixed",
+      }
+    `)
+  })
+
+  test.skipIf(Runtime.get().mode !== 'localnet')(
+    'nulls leg values for unverified tokens',
+    async () => {
+      // Curate only pathUSD so the faucet token queried below is unverified
+      // for this app, and its legs never value.
+      const db = TestApp.database()
+      await TestApp.verifiedSeed(db, Runtime.get().chainId, {
+        tokens: [
+          {
+            address: TestApp.tokenWithHolders,
+            currency: 'USD',
+            decimals: 6,
+            name: 'PathUSD',
+            symbol: 'pathUSD',
+          },
+        ],
+      })
+      const client = TestApp.client({ db })
+
+      const token = Runtime.get().fixtures!.transferTokenAddresses.find(
+        (address) => address.toLowerCase() !== TestApp.tokenWithHolders,
+      )!
+      const response = await client.v1.transfers.$get(
+        { query: { limit: '5', token } },
+        TestApp.auth,
+      )
+      const body = await TestApp.json(response, Transfers.schema.getTransfers.Response)
+
+      expect(response.status).toBe(200)
+      expect(body.data.length).toBeGreaterThan(0)
+      for (const entry of body.data) expect(entry.sourceToken.valuation).toBeNull()
+    },
+  )
+
   test('surfaces a 502 when transfer data is unavailable', async () => {
     // Point at an unreachable indexer so the upstream query fails deterministically.
     const client = TestApp.client({ tidx: { baseUrl: 'http://127.0.0.1:1' } })

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

@@ -17,7 +17,9 @@ import * as Timing from '../../../internal/Timing.js'
 import * as Ttl from '../../../internal/Ttl.js'
 import * as Value from '../../../internal/Value.js'
 import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
+import * as FxOracle from '../FxOracle.js'
 import * as Tokens from './tokens.js'
+import * as Valuation from './valuation.js'
 
 // TIP-20 tokens emit the standard ERC-20 Transfer event. Supplying the
 // signature exposes a decoded `Transfer` CTE (with `from`/`to`/`value`) to
@@ -93,6 +95,14 @@ export namespace schema {
           z.describe('The short ticker symbol wallets and apps show for this token.'),
           z.meta({ examples: ['USDC'] }),
         ),
+      valuation: z
+        .optional(z.nullable(Valuation.schema.Value))
+        .check(
+          z.describe(
+            'The leg’s nominal value in the requested `denomination`. `null` when the token is ' +
+              'unverified, its display currency has no rate, or rates were unavailable.',
+          ),
+        ),
       verified: z
         .optional(z.boolean())
         .check(
@@ -174,6 +184,7 @@ export namespace schema {
         'blockNumber.to': Schema.blockNumberBound('transfers', 'to'),
         chainId: Schema.ChainIdQuery,
         cursor: Schema.Cursor,
+        denomination: Schema.Denomination,
         include: includeQuery,
         limit: Schema.Limit,
         order: Schema.Order,
@@ -266,16 +277,32 @@ export namespace schema {
         ),
       )
 
+    /** Page-level resources: opt-in counts plus valuation rate provenance. */
+    export const Meta = z
+      .object({
+        pricing: z
+          .optional(Valuation.schema.Pricing)
+          .check(
+            z.describe(
+              'Rate provenance for leg 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.'))
+
     /** Page of TIP-20 token transfers across the chain, ordered by block then log index. */
     export const Response = z
       .object({
         data: z.array(Transfer).check(z.describe('The transfers in this page.')),
         // Response-wide `meta` carries the opt-in capped total count
-        // (`include=totalCount`); per-row embeds (`memo`, `token`) attach to
-        // each `data` item, not here.
+        // (`include=totalCount`) and valuation rate provenance; per-row embeds
+        // (`memo`, `token`) attach to each `data` item, not here.
         meta: z
-          .optional(Schema.CountMeta)
-          .check(z.describe('Page-level resources you requested with `include`.')),
+          .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 transfer events across the chain.'))
@@ -283,7 +310,8 @@ export namespace schema {
 }
 
 /** Creates transfer handlers. */
-export function transfers() {
+export function transfers(options: transfers.Options = {}) {
+  const oracle = options.fx?.oracle ?? FxOracle.ecb()
   return new Hono<App.Environment>().get(
     '/v1/transfers',
     Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -319,11 +347,10 @@ export function transfers() {
 
       const options = c.req.valid('query')
       const chainId = options.chainId ?? c.get('chainId')
+      const denomination = options.denomination ?? 'USD'
 
-      // Cursor pages are anchored below the head and effectively immutable,
-      // so cache them aggressively; the head page keeps the route's short
-      // `feed` default.
-      if (options.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+      // Cursor pages carry current valuations and curated verification data.
+      if (options.cursor !== undefined) Cache.setPolicy(c, Cache.policies.metadata)
 
       // Filters shared by the page query and the opt-in total count, so the
       // count always matches the page it annotates.
@@ -427,7 +454,13 @@ export function transfers() {
             return suppress.has(key) ? [] : [transfer]
           })
         }
-        if (options.include.includes('token') && data.length > 0) {
+        // Verification is ancillary to the feed. Skip empty pages and degrade
+        // cold snapshot failures to null valuations.
+        const snapshot =
+          data.length > 0
+            ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+            : undefined
+        if (options.include.includes('token') && data.length > 0 && snapshot) {
           const uniqueTokens = Array.from(
             new Set(
               data.flatMap((transfer) => [
@@ -436,7 +469,6 @@ export function transfers() {
               ]),
             ),
           )
-          const snapshot = await VerifiedTokens.snapshot(c, chainId)
           const resolved = await Timing.time(c, 'tokens', () =>
             Promise.all(
               uniqueTokens.map((token) =>
@@ -466,23 +498,69 @@ export function transfers() {
           }))
         }
 
-        const meta = countPromise ? await countPromise : undefined
+        // Value each leg via its curated display currency, in the requested
+        // denomination.
+        const rates = await Valuation.ratesFor(c, {
+          currencies: data.flatMap((transfer) =>
+            [
+              transfer.sourceToken.address,
+              ...(transfer.destinationToken ? [transfer.destinationToken.address] : []),
+            ].flatMap((address) => {
+              const held = snapshot?.byAddress.get(address.toLowerCase())?.currency
+              return held === undefined ? [] : [held]
+            }),
+          ),
+          denomination,
+          oracle,
+        })
+        const valued = <leg extends { address: string; amount: string }>(leg: leg) => ({
+          ...leg,
+          valuation: Valuation.valuationFor({
+            amount: BigInt(leg.amount),
+            denomination,
+            rates,
+            token: snapshot?.byAddress.get(leg.address.toLowerCase()),
+          }),
+        })
+        data = data.map((transfer) => ({
+          ...transfer,
+          sourceToken: valued(transfer.sourceToken),
+          ...(transfer.destinationToken
+            ? { destinationToken: valued(transfer.destinationToken) }
+            : {}),
+        }))
+
+        const counts = countPromise ? await countPromise : undefined
+        const meta = {
+          ...(rates ? { pricing: Valuation.pricing(rates, oracle) } : {}),
+          ...counts,
+        }
 
         return c.json(
           Response.validated(schema.getTransfers.Response, {
             data,
-            ...(meta ? { meta } : {}),
+            ...(Object.keys(meta).length > 0 ? { meta } : {}),
             nextCursor: page.nextCursor,
           }),
           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)
       }
     },
   )
 }
 
+export declare namespace transfers {
+  /** Options for the transfer handlers. */
+  type Options = {
+    /** FX configuration backing leg valuation. */
+    fx?: Valuation.addresses.Fx | undefined
+  }
+}
+
 /**
  * Shared TIP-20 `Transfer` page query. Used by `GET /transfers` and the
  * webhook poller. Builds the signature-decoded `Transfer` CTE query, applies