tapimo 0.5.3 → 0.7.0

package/src/apps/data/FxOracle.ts

@@ -0,0 +1,153 @@
+import { Value as core_Value } from 'ox'
+
+import * as Ttl from '../../internal/Ttl.js'
+
+/** A pluggable fiat FX rate oracle consumed by the valuation endpoint. */
+export type Oracle = {
+  /** Oracle identifier, surfaced as the valuation's `pricing.source` (e.g. `ecb`). */
+  name: string
+  /** Fetches the oracle's current rate set. */
+  rates: () => Promise<RateSet>
+  /** Cache lifetime for a fetched rate set, in milliseconds. */
+  ttl: number
+}
+
+/** One oracle-published set of exchange rates quoted against a base currency. */
+export type RateSet = {
+  /** Publication date of the rate set as an ISO 8601 timestamp. */
+  asOf: string
+  /** Currency the rates are quoted against (e.g. `EUR`). */
+  base: string
+  /** Currency code to units of that currency per one `base` unit, as decimal strings. */
+  rates: Record<string, string>
+}
+
+/** Fixed-point scale (decimal places) of cross rates returned by {@link rate}. */
+export const precision = 18
+
+/** Canonical ECB daily reference-rate feed (public, no key required). */
+export const ecbUrl = 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml'
+
+/**
+ * Normalizes an oracle definition into an {@link Oracle}: applies the default
+ * `ttl` and rethrows `rates()` failures as {@link RatesError}.
+ */
+export function from(oracle: from.Value): Oracle {
+  return {
+    name: oracle.name,
+    rates: async () => {
+      try {
+        return await oracle.rates()
+      } catch (cause) {
+        throw new RatesError(oracle.name, { cause })
+      }
+    },
+    ttl: oracle.ttl ?? Ttl.hours(1),
+  }
+}
+
+export declare namespace from {
+  /** Oracle definition accepted by {@link from}. */
+  type Value = Pick<Oracle, '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.
+ */
+export function ecb(options: ecb.Options = {}): Oracle {
+  const { fetch = globalThis.fetch, url = ecbUrl } = options
+  return from({
+    name: 'ecb',
+    rates: async () => {
+      const response = await fetch(url, {
+        headers: { accept: 'application/xml' },
+        signal: AbortSignal.timeout(10_000),
+      })
+      if (!response.ok) throw new ResponseError(response.status)
+      const text = await response.text()
+
+      // The daily file is a flat, stable XML shape; extract the `Cube`
+      // attributes directly rather than pulling in an XML parser.
+      const asOf = text.match(/<Cube time=['"](\d{4}-\d{2}-\d{2})['"]/)?.[1]
+      const rates: Record<string, string> = {}
+      for (const match of text.matchAll(
+        /<Cube currency=['"]([A-Z]{3})['"] rate=['"]([^'"]*)['"]/g,
+      )) {
+        const [, code, value] = match
+        if (
+          !code ||
+          !value ||
+          !/^\d+(?:\.\d+)?$/.test(value) ||
+          core_Value.from(value, precision) <= 0n
+        )
+          throw new ParseError()
+        rates[code] = value
+      }
+      if (!asOf || rates['USD'] === undefined) throw new ParseError()
+      return { asOf: `${asOf}T00:00:00.000Z`, base: 'EUR', rates }
+    },
+  })
+}
+
+export declare namespace ecb {
+  /** Options for the ECB oracle. */
+  type Options = {
+    /** Fetch implementation used to retrieve the feed. @default `globalThis.fetch` */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Feed URL. @default {@link ecbUrl} */
+    url?: string | undefined
+  }
+}
+
+/**
+ * Derives the cross rate from one currency to another through the set's base,
+ * scaled to {@link precision} decimal places. Returns `undefined` when the set
+ * prices neither leg of a currency.
+ */
+export function rate(set: RateSet, options: rate.Options): bigint | undefined {
+  const scaled = (code: string) => {
+    if (code === set.base) return 10n ** BigInt(precision)
+    const value = set.rates[code]
+    return value === undefined ? undefined : core_Value.from(value, precision)
+  }
+  const source = scaled(options.from)
+  const target = scaled(options.to)
+  if (source === undefined || target === undefined || source === 0n) return undefined
+  return (target * 10n ** BigInt(precision)) / source
+}
+
+export declare namespace rate {
+  /** Options for deriving a cross rate. */
+  type Options = {
+    /** Currency code to convert from. */
+    from: string
+    /** Currency code to convert to. */
+    to: string
+  }
+}
+
+/** Thrown when an oracle fails to produce its rate set. */
+export class RatesError extends Error {
+  override name = 'FxOracle.RatesError'
+  constructor(oracle: string, options: { cause: unknown }) {
+    super(`FX oracle "${oracle}" failed to produce rates`, options)
+  }
+}
+
+class ParseError extends Error {
+  override name = 'FxOracle.ParseError'
+  constructor() {
+    super('Rate feed returned an unrecognized payload')
+  }
+}
+
+class ResponseError extends Error {
+  override name = 'FxOracle.ResponseError'
+  constructor(status: number) {
+    super(`Rate feed request failed with status ${status}`)
+  }
+}

package/src/apps/data/index.ts

@@ -1,3 +1,4 @@
 export { data } from './App.js'
 export * as FundingQuoteProviders from './FundingQuoteProviders.js'
+export * as FxOracle from './FxOracle.js'
 export * as Sponsorships from '../relay/Sponsorships.js'

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

@@ -1,12 +1,24 @@
-import { Address, Hex } from 'ox'
+import { Address, Hex, Value as core_Value } from 'ox'
+import { FxOracle } from 'tapimo/apps'
 import { encodeAbiParameters, encodeEventTopics } from 'viem'
 import { Abis } from 'viem/tempo'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
+import * as Cursor from '../../../internal/Cursor.js'
 import * as Store from '../../../internal/Store.js'
 import * as Activities from './activities.js'
 
+// Deterministic EUR-based rate set so conversion math is exact in assertions.
+const fixed = FxOracle.from({
+  name: 'fixed',
+  rates: async () => ({
+    asOf: '2026-01-01T00:00:00.000Z',
+    base: 'EUR',
+    rates: { AUD: '1.6', USD: '1.0' },
+  }),
+})
+
 /**
  * Real Tempo (Moderato) accounts, each exercising specific activity types.
  * Discovered by scanning indexed `logs` for the event each type classifies
@@ -102,6 +114,32 @@ function find(items: readonly Activities.Entry[], type: string): Activities.Entr
 }
 
 describe('GET /addresses/:address/activities', () => {
+  test('parses granular token includes for both activity endpoints', () => {
+    expect(
+      Activities.schema.getAddressActivities.Query.parse({
+        include: 'token.logoUri,token.verified',
+      }).include,
+    ).toMatchInlineSnapshot(`
+      [
+        "token.logoUri",
+        "token.verified",
+      ]
+    `)
+    expect(
+      Activities.schema.getTransactionActivities.Query.parse({
+        include: 'token.logoUri,token.verified',
+      }).include,
+    ).toMatchInlineSnapshot(`
+      [
+        "token.logoUri",
+        "token.verified",
+      ]
+    `)
+    expect(
+      Activities.schema.getAddressActivities.Query.safeParse({ include: 'token' }).success,
+    ).toBe(false)
+  })
+
   test('returns a newest-first, schema-valid feed with timing', async () => {
     const response = await request(accounts.keychain, { limit: '10' })
     expect(response.status).toBe(200)
@@ -130,7 +168,31 @@ describe('GET /addresses/:address/activities', () => {
     expect(transfer.data.transactionHash).toMatch(/^0x[0-9a-f]{64}$/)
     expect(typeof transfer.data.blockNumber).toBe('number')
     expect(transfer.data.sourceToken.address).toMatch(/^0x[0-9a-f]{40}$/)
-    expect(transfer.data.sourceToken.amount).toMatch(/^\d+$/)
+    expect(transfer.data.sourceToken).not.toHaveProperty('amount')
+    expect(typeof transfer.data.sourceToken.currency).toBe('string')
+    expect(typeof transfer.data.sourceToken.decimals).toBe('number')
+    expect(typeof transfer.data.sourceToken.name).toBe('string')
+    expect(typeof transfer.data.sourceToken.symbol).toBe('string')
+    expect(transfer.data.sourceAmount.baseUnits).toMatch(/^\d+$/)
+    expect(transfer.data.sourceAmount.currency).toBe(transfer.data.sourceToken.currency)
+    expect(transfer.data.sourceAmount.decimals).toBe(transfer.data.sourceToken.decimals)
+    expect(transfer.data.sourceAmount.formatted).toMatch(/^\d+(\.\d+)?$/)
+    expect(transfer.data.sourceToken.logoUri).toBeUndefined()
+    expect(transfer.data.sourceToken.verified).toBeUndefined()
+  })
+
+  test('includes requested token verification', async () => {
+    const transfer = find(
+      (
+        await activities(accounts.creator, {
+          include: 'token.logoUri,token.verified',
+        })
+      ).data,
+      'transfer',
+    )
+    expect(transfer?.type).toBe('transfer')
+    if (transfer?.type !== 'transfer') return
+    expect(typeof transfer.data.sourceToken.verified).toBe('boolean')
   })
 
   test.skipIf(runtime.mode === 'localnet')('swap data carries both sides of the swap', async () => {
@@ -139,8 +201,30 @@ describe('GET /addresses/:address/activities', () => {
     if (swap?.type !== 'swap') return
     expect(swap.data.sourceToken.address).toMatch(/^0x[0-9a-f]{40}$/)
     expect(swap.data.destinationToken.address).toMatch(/^0x[0-9a-f]{40}$/)
+    expect(swap.data.sourceToken).not.toHaveProperty('amount')
+    expect(swap.data.destinationToken).not.toHaveProperty('amount')
+    expect(swap.data.sourceAmount.baseUnits).toMatch(/^\d+$/)
+    expect(swap.data.destinationAmount.baseUnits).toMatch(/^\d+$/)
   })
 
+  test.skipIf(runtime.mode === 'localnet')(
+    'adds a structured refund amount when a session closes with a refund',
+    async () => {
+      const session = find((await activities(accounts.channel)).data, 'session-closed')
+      expect(session?.type).toBe('session-closed')
+      if (session?.type !== 'session-closed') return
+      if (!session.data.refund) {
+        expect(session.data.refundAmount).toBeUndefined()
+        return
+      }
+      expect(session.data.refundAmount).toBeDefined()
+      expect(session.data.refund).not.toHaveProperty('amount')
+      expect(session.data.refundAmount?.baseUnits).toMatch(/^\d+$/)
+      expect(session.data.refundAmount?.currency).toBe(session.data.refund.currency)
+      expect(session.data.refundAmount?.decimals).toBe(session.data.refund.decimals)
+    },
+  )
+
   test.skipIf(runtime.mode !== 'localnet')(
     'surfaces a cross-token transfer as outgoing in the sender feed',
     async () => {
@@ -162,6 +246,10 @@ describe('GET /addresses/:address/activities', () => {
       expect(transfer.data.recipient).toBe(crossToken.recipient)
       expect(transfer.data.sourceToken.address).toBe(crossToken.sourceToken)
       expect(transfer.data.destinationToken?.address).toBe(crossToken.destinationToken)
+      expect(transfer.data.sourceToken).not.toHaveProperty('amount')
+      expect(transfer.data.destinationToken).not.toHaveProperty('amount')
+      expect(transfer.data.sourceAmount.baseUnits).toMatch(/^\d+$/)
+      expect(transfer.data.destinationAmount?.baseUnits).toMatch(/^\d+$/)
     },
   )
 
@@ -202,6 +290,39 @@ describe('GET /addresses/:address/activities', () => {
     },
   )
 
+  test.skipIf(runtime.mode !== 'localnet')('values curated activity amounts', async () => {
+    const db = TestApp.database()
+    await TestApp.verifiedSeed(db, runtime.chainId)
+    const client = TestApp.client({ db, fx: { oracle: fixed } })
+    const hash = runtime.fixtures!.faucetTransactionHashes[0]!
+
+    const response = await client.v1.transactions[':transactionHash'].activities.$get(
+      { param: { transactionHash: hash }, query: { denomination: 'AUD' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Activities.schema.getTransactionActivities.Response)
+    expect(response.status).toBe(200)
+
+    // The faucet transaction moves curated USD tokens; their amounts value at
+    // the fixed 1.6 USD -> AUD rate.
+    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(amount.valuation).toEqual({
+        amount: core_Value.format((BigInt(amount.baseUnits) * 16n) / 10n, 6),
+        currency: 'AUD',
+      })
+    expect(body.meta?.pricing).toMatchInlineSnapshot(`
+      {
+        "asOf": "2026-01-01T00:00:00.000Z",
+        "basis": "nominal",
+        "source": "fixed",
+      }
+    `)
+  })
+
   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)
@@ -210,9 +331,34 @@ describe('GET /addresses/:address/activities', () => {
   test('paginates with an opaque cursor', async () => {
     const first = await activities(accounts.keychain, { limit: '5' })
     if (!first.nextCursor) return
-    const second = await activities(accounts.keychain, { limit: '5', cursor: first.nextCursor })
+    const response = await request(accounts.keychain, { limit: '5', cursor: first.nextCursor })
+    expect(response.headers.get('cache-control')).toMatchInlineSnapshot(
+      `"private, max-age=60, stale-while-revalidate=300"`,
+    )
+    const second = await TestApp.json(response, Activities.schema.getAddressActivities.Response)
     expect(Array.isArray(second.data)).toBe(true)
   })
+
+  test('validates denominations on empty feeds', async () => {
+    const client = TestApp.client({ fx: { oracle: fixed } })
+    const cursor = Cursor.encode([0, 0])
+    const emptyResponse = await client.v1.addresses[':address'].activities.$get(
+      { param: { address: accounts.keychain }, query: { cursor, limit: '5' } },
+      TestApp.auth,
+    )
+    const empty = await TestApp.json(emptyResponse, Activities.schema.getAddressActivities.Response)
+    expect(emptyResponse.status).toBe(200)
+    expect(empty.data).toMatchInlineSnapshot(`[]`)
+
+    const response = await client.v1.addresses[':address'].activities.$get(
+      {
+        param: { address: accounts.keychain },
+        query: { cursor, denomination: 'JPY', limit: '5' },
+      },
+      TestApp.auth,
+    )
+    expect(response.status).toBe(400)
+  })
 })
 
 /** Resolves a real transaction hash from an address's (non-grouped) activity feed. */
@@ -239,6 +385,9 @@ describe('GET /transactions/:transactionHash/activities', () => {
 
     const response = await transactionActivitiesRequest(transactionHash)
     expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toMatchInlineSnapshot(
+      `"private, max-age=60, stale-while-revalidate=300"`,
+    )
     expect(response.headers.get('server-timing')?.includes('transaction_activities;dur=')).toBe(
       true,
     )
@@ -262,6 +411,27 @@ describe('GET /transactions/:transactionHash/activities', () => {
     )
   })
 
+  test('supports requested token verification', async () => {
+    const address = await activities(accounts.creator)
+    const entry = address.data.find((item) => item.type !== 'group' && 'sourceToken' in item.data)
+    expect(entry?.type).not.toBe('group')
+    if (!entry || entry.type === 'group') return
+
+    const body = await TestApp.json(
+      await transactionActivitiesRequest(entry.transactionHash, {
+        include: 'token.verified',
+      }),
+      Activities.schema.getTransactionActivities.Response,
+    )
+    const item = body.data.find((item) => 'sourceToken' in item.data)
+    expect(item).toBeDefined()
+    if (!item || !('sourceToken' in item.data) || !item.data.sourceToken || !item.data.sourceAmount)
+      return
+    expect(typeof item.data.sourceToken.verified).toBe('boolean')
+    expect(item.data.sourceToken).not.toHaveProperty('amount')
+    expect(item.data.sourceAmount.baseUnits).toMatch(/^\d+$/)
+  })
+
   test.skipIf(runtime.mode !== 'localnet')(
     'classifies a seeded cross-token transfer with both source and destination tokens',
     async () => {
@@ -283,6 +453,10 @@ describe('GET /transactions/:transactionHash/activities', () => {
       expect(transfer.data.recipient).toBe(crossToken.recipient)
       expect(transfer.data.sourceToken.address).toBe(crossToken.sourceToken)
       expect(transfer.data.destinationToken?.address).toBe(crossToken.destinationToken)
+      expect(transfer.data.sourceToken).not.toHaveProperty('amount')
+      expect(transfer.data.destinationToken).not.toHaveProperty('amount')
+      expect(transfer.data.sourceAmount.baseUnits).toMatch(/^\d+$/)
+      expect(transfer.data.destinationAmount?.baseUnits).toMatch(/^\d+$/)
     },
   )