tapimo 0.8.0 → 0.10.0

package/src/apps/composition.test.ts

@@ -18,7 +18,12 @@ async function document(app: { request: (path: string) => Promise<Response> | Re
       string,
       Partial<Record<'get' | 'post', { operationId: string; tags?: readonly string[] | undefined }>>
     >
-    tags: readonly { description: string; name: string }[]
+    tags: readonly {
+      description: string
+      name: string
+      'x-displayName'?: string | undefined
+      'x-pagePath'?: string | undefined
+    }[]
     webhooks?: Record<string, unknown> | undefined
     'x-tagGroups'?: readonly { name: string; tags: readonly string[] }[] | undefined
   }
@@ -294,7 +299,6 @@ describe('funding()', () => {
         '/v1/funding/chains',
         '/v1/funding/deposit-addresses',
         '/v1/funding/deposit-addresses/{id}',
-        '/v1/funding/deposit-addresses/{id}/deposits',
         '/v1/funding/deposit-addresses/{id}/reconcile',
         '/v1/funding/deposits',
         '/v1/funding/deposits/{id}',
@@ -311,7 +315,7 @@ describe('funding()', () => {
     expect(spec['x-tagGroups']).toEqual([
       {
         name: 'Funding & Bridge API',
-        tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Transfers'],
+        tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Funding Transfers'],
       },
     ])
     expect(
@@ -325,13 +329,12 @@ describe('funding()', () => {
       'reconcileFundingDepositAddress',
       'getFundingDepositAddress',
       'getFundingDeposit',
-      'listFundingDepositAddressDeposits',
       'listFundingDeposits',
     ])
     expect((await app.request('/v1/tokens')).status).toBe(404)
   })
 
-  test('maps operations to five tags and reuses Transfers across groups', async () => {
+  test('keeps data and funding transfers separate with the same display name', async () => {
     const app = App.create({ auth: false, db: TestApp.database() })
       .route('/', data())
       .route('/', funding())
@@ -344,9 +347,10 @@ describe('funding()', () => {
     expect({
       chains: operationTag('/v1/funding/chains', 'get'),
       depositAddress: operationTag('/v1/funding/deposit-addresses', 'post'),
-      deposits: operationTag('/v1/funding/deposit-addresses/{id}/deposits', 'get'),
+      deposits: operationTag('/v1/funding/deposits', 'get'),
       providers: operationTag('/v1/funding/providers', 'get'),
       quotes: operationTag('/v1/funding/quotes', 'get'),
+      tokenTransfers: operationTag('/v1/transfers', 'get'),
       transfers: operationTag('/v1/funding/transfers', 'get'),
       vault: operationTag('/v1/funding/transfers/vault', 'post'),
       zone: operationTag('/v1/funding/transfers/zone', 'post'),
@@ -356,17 +360,42 @@ describe('funding()', () => {
       deposits: ['Deposit Addresses'],
       providers: ['Providers'],
       quotes: ['Quotes'],
-      transfers: ['Transfers'],
-      vault: ['Transfers'],
-      zone: ['Transfers'],
+      tokenTransfers: ['Transfers'],
+      transfers: ['Funding Transfers'],
+      vault: ['Funding Transfers'],
+      zone: ['Funding Transfers'],
     })
 
     const groups = Object.fromEntries(
       (spec['x-tagGroups'] ?? []).map((group) => [group.name, group.tags]),
     )
     expect(groups['Data API']).toContain('Transfers')
-    expect(groups['Funding & Bridge API']).toContain('Transfers')
+    expect(groups['Data API']).not.toContain('Funding Transfers')
+    expect(groups['Funding & Bridge API']).toContain('Funding Transfers')
+    expect(groups['Funding & Bridge API']).not.toContain('Transfers')
     expect(spec.tags.filter((tag) => tag.name === 'Transfers')).toHaveLength(1)
+    expect(spec.tags.filter((tag) => tag.name === 'Funding Transfers')).toEqual([
+      {
+        description: 'Inbound funding transfers.',
+        name: 'Funding Transfers',
+        'x-displayName': 'Transfers',
+        'x-pagePath': 'funding/transfers',
+      },
+    ])
+    expect(
+      Object.fromEntries(
+        (groups['Funding & Bridge API'] ?? []).map((name) => {
+          const tag = spec.tags.find((tag) => tag.name === name)
+          return [tag?.['x-displayName'] ?? tag?.name, tag?.['x-pagePath']]
+        }),
+      ),
+    ).toEqual({
+      Chains: 'funding/chains',
+      'Deposit Addresses': 'funding/deposit-addresses',
+      Providers: 'funding/providers',
+      Quotes: 'funding/quotes',
+      Transfers: 'funding/transfers',
+    })
   })
 })
 

package/src/apps/data/FxOracle.test.ts

@@ -41,6 +41,24 @@ describe('from', () => {
 })
 
 describe('ecb', () => {
+  test('caches the daily feed for one day', () => {
+    expect(FxOracle.ecb({ url: feedUrl('1.25') }).ttl).toMatchInlineSnapshot(`86400000`)
+  })
+
+  test('rotates the cache key after the daily publication window', () => {
+    vi.useFakeTimers()
+    try {
+      const oracle = FxOracle.ecb({ url: feedUrl('1.25') })
+
+      vi.setSystemTime('2026-01-02T15:59:00.000Z')
+      expect(oracle.cacheKey?.()).toMatchInlineSnapshot(`"ecb:2026-01-01"`)
+      vi.setSystemTime('2026-01-02T16:00:00.000Z')
+      expect(oracle.cacheKey?.()).toMatchInlineSnapshot(`"ecb:2026-01-02"`)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   test('fetches and parses the daily reference rates', async () => {
     const rates = await FxOracle.ecb({ url: feedUrl('1.25') }).rates()
     expect(rates).toMatchInlineSnapshot(`

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

@@ -3,6 +3,7 @@
 import { Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
 import { Value as core_Value } from 'ox'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { Actions } from 'viem/tempo'
 
 import * as TestApp from '../../../../test/App.js'
@@ -296,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',
         },
       ],
     })
@@ -320,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 () => {
@@ -359,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
@@ -370,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 () => {
@@ -443,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
@@ -469,3 +542,81 @@ describe('GET /addresses/:address/balances', () => {
     expect(body.meta!.totalCount).toBeGreaterThanOrEqual(body.data.length)
   })
 })
+
+describe('GET /v1/addresses/:address/balances/:token', () => {
+  test('returns one live balance without indexed holder discovery', 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: {},
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalance.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.id).toBe(TestApp.tokenWithHolders)
+    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 () => {
+    const client = app()
+    const response = await client.v1.addresses[':address'].balances[':token'].$get(
+      {
+        param: {
+          address: privateKeyToAccount(generatePrivateKey()).address,
+          token: TestApp.tokenWithHolders,
+        },
+        query: {},
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalance.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.amount).toBe('0')
+    expect(body.formatted).toBe('0')
+  })
+})