tapimo 0.9.0 → 0.10.0

package/src/apps/data/FxOracle.ts

@@ -4,6 +4,8 @@ import * as Ttl from '../../internal/Ttl.js'
 
 /** A pluggable fiat FX rate oracle consumed by the valuation endpoint. */
 export type Oracle = {
+  /** Returns the cache-key suffix for the oracle's current publication window. */
+  cacheKey?: (() => string) | undefined
   /** Oracle identifier, surfaced as valuation rate provenance (e.g. `ecb`). */
   name: string
   /** Fetches the oracle's current rate set. */
@@ -34,6 +36,7 @@ export const ecbUrl = 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily
  */
 export function from(oracle: from.Value): Oracle {
   return {
+    ...(oracle.cacheKey ? { cacheKey: oracle.cacheKey } : {}),
     name: oracle.name,
     rates: async () => {
       try {
@@ -48,19 +51,17 @@ export function from(oracle: from.Value): Oracle {
 
 export declare namespace from {
   /** Oracle definition accepted by {@link from}. */
-  type Value = Pick<Oracle, 'name' | 'rates'> & {
+  type Value = Pick<Oracle, 'cacheKey' | 'name' | 'rates'> & {
     /** Cache lifetime for a fetched rate set, in milliseconds. @default `Ttl.hours(1)` */
     ttl?: number | undefined
   }
 }
 
-/**
- * European Central Bank euro reference rates: one EUR-based set covering ~30
- * currencies, published once per working day.
- */
+/** European Central Bank reference rates, cached for one day to match their publication cadence. */
 export function ecb(options: ecb.Options = {}): Oracle {
   const { fetch = globalThis.fetch, url = ecbUrl } = options
   return from({
+    cacheKey: () => `ecb:${ecbPublication(new Date())}`,
     name: 'ecb',
     rates: async () => {
       const response = await fetch(url, {
@@ -90,9 +91,31 @@ export function ecb(options: ecb.Options = {}): Oracle {
       if (!asOf || rates['USD'] === undefined) throw new ParseError()
       return { asOf: `${asOf}T00:00:00.000Z`, base: 'EUR', rates }
     },
+    ttl: Ttl.days(1),
   })
 }
 
+const ecbTime = new Intl.DateTimeFormat('en-CA', {
+  day: '2-digit',
+  hour: '2-digit',
+  hourCycle: 'h23',
+  month: '2-digit',
+  timeZone: 'Europe/Brussels',
+  year: 'numeric',
+})
+
+function ecbPublication(now: Date) {
+  const parts = Object.fromEntries(
+    ecbTime.formatToParts(now).map((part) => [part.type, part.value]),
+  )
+  // Rotate one hour after the ECB's usual 16:00 CET publication time.
+  const date = Number(parts['hour']) >= 17 ? now : new Date(now.getTime() - Ttl.days(1))
+  const publication = Object.fromEntries(
+    ecbTime.formatToParts(date).map((part) => [part.type, part.value]),
+  )
+  return `${publication['year']}-${publication['month']}-${publication['day']}`
+}
+
 export declare namespace ecb {
   /** Options for the ECB oracle. */
   type Options = {

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

@@ -328,6 +328,25 @@ describe('GET /addresses/:address/activities', () => {
     `)
   })
 
+  test.skipIf(runtime.mode !== 'localnet')('omits activity valuations by default', async () => {
+    const response = await client.v1.transactions[':transactionHash'].activities.$get(
+      {
+        param: { transactionHash: runtime.fixtures!.faucetTransactionHashes[0]! },
+        query: {},
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Activities.schema.getTransactionActivities.Response)
+    expect(response.status).toBe(200)
+
+    const amounts = body.data.flatMap((item) =>
+      item.type === 'transfer' || item.type === 'mint' ? [item.data.sourceAmount] : [],
+    )
+    expect(amounts.length).toBeGreaterThan(0)
+    for (const amount of amounts) expect('valuation' in amount).toBe(false)
+    expect(response.headers.get('server-timing')).not.toContain('valuation_rates;dur=')
+  })
+
   test('returns every item at the root by default (no group entries)', async () => {
     const body = await activities(accounts.channel)
     expect(body.data.every((entry) => entry.type !== 'group')).toBe(true)

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

@@ -1853,7 +1853,7 @@ export function addresses(options: addresses.Options = {}) {
       const { address } = c.req.valid('param')
       const query = c.req.valid('query')
 
-      // Cursor pages carry current valuations and curated verification data.
+      // Cursor pages can carry current valuations and curated verification data.
       if (query.cursor !== undefined) Cache.setPolicy(c, Cache.policies.metadata)
 
       try {
@@ -1884,7 +1884,7 @@ export function addresses(options: addresses.Options = {}) {
         // Build immutable token and structured amount copies from RPC metadata.
         const { items, rates } = await enrichTokens(c, {
           chainId,
-          denomination: query['valuation.currency'] ?? 'USD',
+          denomination: query['valuation.currency'],
           include: query.include,
           items: unenrichedItems,
           oracle,
@@ -1964,7 +1964,7 @@ export function transactions(options: transactions.Options = {}) {
     }),
     Cache.response<App.Environment>({
       // Default to no-store so a 404 does not mask the eventual mined result.
-      // Successful responses use the metadata policy for current valuations.
+      // Successful responses use the metadata policy for optional valuations.
       cacheControl: Cache.policies.noStore,
       name: 'tempo-api:transactions:v1',
       key: (c) => Cache.urlKey(c, schema.getTransactionActivities.Query),
@@ -2012,13 +2012,13 @@ export function transactions(options: transactions.Options = {}) {
             status: 404,
           })
 
-        // Mined activity still carries current valuations and verification data.
+        // Mined activity can carry current valuations and verification data.
         Cache.setPolicy(c, Cache.policies.metadata)
 
         // Build immutable token and structured amount copies from RPC metadata.
         const { items, rates } = await enrichTokens(c, {
           chainId,
-          denomination: query['valuation.currency'] ?? 'USD',
+          denomination: query['valuation.currency'],
           include: query.include,
           items: unenrichedItems,
           oracle,
@@ -4088,27 +4088,27 @@ async function enrichTokens(
   const { chainId, denomination, include, items, oracle } = options
   const addresses = new Set<Address.Address>()
   for (const item of items) collectTokens(item, addresses)
-  // Valuation keys off the curated snapshot; a snapshot failure degrades the
-  // values to `null` rather than failing the feed.
+  const includeLogoUri = include.includes('token.logoUri')
+  const includeVerified = include.includes('token.verified')
+  // Curated data is needed only for requested valuation or token fields.
   const snapshot =
-    addresses.size > 0
+    addresses.size > 0 && (denomination !== undefined || includeLogoUri || includeVerified)
       ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
       : undefined
-  const rates = await Valuation.ratesFor(c, {
-    currencies: snapshot
-      ? [...addresses].flatMap((address) => {
-          const held = snapshot.byAddress.get(address)?.currency
-          return held === undefined ? [] : [held]
-        })
-      : [],
-    denomination,
-    oracle,
-  })
+  const rates = denomination
+    ? await Valuation.ratesFor(c, {
+        currencies: snapshot
+          ? [...addresses].flatMap((address) => {
+              const held = snapshot.byAddress.get(address)?.currency
+              return held === undefined ? [] : [held]
+            })
+          : [],
+        denomination,
+        oracle,
+      })
+    : undefined
   if (addresses.size === 0) return { items: items as Item[], rates }
 
-  const includeLogoUri = include.includes('token.logoUri')
-  const includeVerified = include.includes('token.verified')
-
   const resolved = await Timing.time(c, 'tokens', () =>
     Promise.all(
       [...addresses].map(async (address) => {
@@ -4145,7 +4145,7 @@ declare namespace enrichTokens {
   type Options = {
     chainId: z.output<typeof Schema.ChainId>
     /** Currency the amount valuations are denominated in (uppercase). */
-    denomination: string
+    denomination?: string | undefined
     include: readonly z.output<typeof schema.Include>[]
     items: readonly UnenrichedItem[]
     /** FX rate oracle backing amount valuation. */
@@ -4173,13 +4173,17 @@ function enrichItem(
         currency: meta.currency,
         decimals: meta.decimals,
       }),
-      // Valued via the curated display currency, never the on-chain metadata.
-      valuation: Valuation.valuationFor({
-        amount: BigInt(t.amount),
-        denomination: valuation.denomination,
-        rates: valuation.rates,
-        token: valuation.snapshot?.byAddress.get(t.address.toLowerCase()),
-      }),
+      ...(valuation.denomination
+        ? {
+            // Valued via the curated display currency, never the on-chain metadata.
+            valuation: Valuation.valuationFor({
+              amount: BigInt(t.amount),
+              denomination: valuation.denomination,
+              rates: valuation.rates,
+              token: valuation.snapshot?.byAddress.get(t.address.toLowerCase()),
+            }),
+          }
+        : {}),
     }
     data[key] = {
       address: t.address,
@@ -4198,7 +4202,7 @@ declare namespace enrichItem {
   /** Valuation inputs threaded from {@link enrichTokens}. */
   type Valuation = {
     /** Currency the amount valuations are denominated in (uppercase). */
-    denomination: string
+    denomination?: string | undefined
     /** Oracle rate set, when loaded. */
     rates: FxOracle.RateSet | undefined
     /** Compiled verified-token snapshot, when available. */

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

@@ -297,8 +297,8 @@ describe('GET /addresses/:address/balances', () => {
           currency: 'USD',
           decimals: 6,
           logoUri: 'https://example.com/pathusd.svg',
-          name: 'PathUSD',
-          symbol: 'pathUSD',
+          name: 'Curated PathUSD',
+          symbol: 'curatedUSD',
         },
       ],
     })
@@ -321,9 +321,49 @@ describe('GET /addresses/:address/balances', () => {
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
     expect(response.status).toBe(200)
     expect(body.data.length).toBeGreaterThan(0)
+    expect(response.headers.get('server-timing')).not.toContain('token_logo;dur=')
+    expect(response.headers.get('server-timing')).not.toContain('token_metadata;dur=')
     for (const balance of body.data) expect(balance.token.verified).toBe(true)
     const pathUsd = body.data.find((balance) => balance.token.address === TestApp.tokenWithHolders)
-    expect(pathUsd?.token.logoUri).toMatch(/^http/)
+    expect(pathUsd?.token).toMatchObject({
+      logoUri: 'https://example.com/pathusd.svg',
+      name: 'Curated PathUSD',
+      symbol: 'curatedUSD',
+    })
+  })
+
+  test('includes uploaded logos for verified tokens without a logo URI', async () => {
+    const logoDb = TestApp.database()
+    await TestApp.verifiedSeed(logoDb, runtime.chainId, {
+      tokens: [
+        {
+          address: TestApp.tokenWithHolders,
+          currency: 'USD',
+          decimals: 6,
+          name: 'Curated PathUSD',
+          symbol: 'curatedUSD',
+        },
+      ],
+    })
+    const client = app({ db: logoDb })
+    const holder = await holderWithBalance
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      {
+        param: { address: holder },
+        query: { limit: '20', verified: 'true' },
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+    const pathUsd = body.data.find((balance) => balance.token.address === TestApp.tokenWithHolders)
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')).toContain('token_logo;dur=')
+    expect(response.headers.get('server-timing')).not.toContain('token_metadata;dur=')
+    expect(pathUsd?.token.logoUri).toBe(
+      `http://localhost/assets/${runtime.chainId}/icons/${TestApp.tokenWithHolders}`,
+    )
   })
 
   test('narrows balances by currency and retains verification', async () => {
@@ -360,7 +400,23 @@ describe('GET /addresses/:address/balances', () => {
     for (const balance of body.data) expect(typeof balance.feeEligible).toBe('boolean')
   })
 
-  test('values each verified holding in the default denomination', async () => {
+  test('skips the fee-token lookup when an address has no holdings', async () => {
+    const client = app()
+    const response = await client.v1.addresses[':address'].balances.$get(
+      {
+        param: { address: privateKeyToAccount(generatePrivateKey()).address },
+        query: {},
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.data).toEqual([])
+    expect(response.headers.get('server-timing')).not.toContain('fee_token_set;dur=')
+  })
+
+  test('omits valuations unless a denomination is requested', async () => {
     await TestApp.verifiedSeed(db, runtime.chainId)
     const client = app()
     const holder = await holderWithBalance
@@ -371,12 +427,8 @@ describe('GET /addresses/:address/balances', () => {
     )
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
     expect(response.status).toBe(200)
-
-    // The guaranteed pathUSD holding is curated USD, so its USD value is the
-    // holding itself; unverified holdings are never valued.
-    const pathUsd = body.data.find((entry) => entry.token.address === TestApp.tokenWithHolders)
-    expect(pathUsd?.valuation).toEqual({ amount: pathUsd!.formatted, currency: 'USD' })
-    for (const entry of body.data) if (!entry.token.verified) expect(entry.valuation).toBeNull()
+    expect(response.headers.get('server-timing')).not.toContain('valuation_rates;dur=')
+    for (const entry of body.data) expect('valuation' in entry).toBe(false)
   })
 
   test('values holdings in a requested denomination', async () => {
@@ -444,6 +496,26 @@ describe('GET /addresses/:address/balances', () => {
     expect(stable.error.code).toMatchInlineSnapshot(`"query_invalid"`)
   })
 
+  test('rejects unsupported denominations before balance RPC failures', async () => {
+    const client = app({
+      fx: { oracle: fixed },
+      rpc: { url: () => 'http://127.0.0.1:1' },
+    })
+    const holder = await holderWithBalance
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      {
+        param: { address: holder },
+        query: { 'valuation.currency': 'JPY' },
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(body.error.code).toMatchInlineSnapshot(`"query_invalid"`)
+  })
+
   test('restricts the page to fee tokens when feeEligible=true', async () => {
     const client = app()
     const holder = await holderWithBalance
@@ -489,7 +561,44 @@ describe('GET /v1/addresses/:address/balances/:token', () => {
     expect(body.token.address).toBe(TestApp.tokenWithHolders)
     expect(body.amount).toMatch(/^\d+$/)
     expect(core_Value.from(body.formatted, body.decimals)).toBe(BigInt(body.amount))
+    expect('valuation' in body).toBe(false)
+    expect(response.headers.get('server-timing')).not.toContain('valuation_rates;dur=')
+  })
+
+  test('values one balance when a denomination is requested', async () => {
+    const client = app()
+    const holder = await holderWithBalance
+    const response = await client.v1.addresses[':address'].balances[':token'].$get(
+      {
+        param: { address: holder, token: TestApp.tokenWithHolders },
+        query: { 'valuation.currency': 'USD' },
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalance.Response)
+
+    expect(response.status).toBe(200)
     expect(body.valuation).toEqual({ amount: body.formatted, currency: 'USD' })
+    expect(response.headers.get('server-timing')).toContain('valuation_rates;dur=')
+  })
+
+  test('rejects an unsupported denomination before a balance RPC failure', async () => {
+    const client = app({
+      fx: { oracle: fixed },
+      rpc: { url: () => 'http://127.0.0.1:1' },
+    })
+    const holder = await holderWithBalance
+    const response = await client.v1.addresses[':address'].balances[':token'].$get(
+      {
+        param: { address: holder, token: TestApp.tokenWithHolders },
+        query: { 'valuation.currency': 'JPY' },
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(body.error.code).toMatchInlineSnapshot(`"query_invalid"`)
   })
 
   test('returns zero for a token the account does not hold', async () => {