tapimo 0.5.3 → 0.7.0

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

@@ -5,9 +5,11 @@ import type * as App from '../../../App.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
 import * as FundingQuotes from '../../../internal/FundingQuotes.js'
+import type * as Log from '../../../internal/Log.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
+import * as Value from '../../../internal/Value.js'
 import * as FundingQuoteProviders from '../FundingQuoteProviders.js'
 
 /** Zod schemas owned by funding quote resources. */
@@ -57,6 +59,12 @@ export namespace schema {
           z.describe('Contract address, mint, or issuer address on the token chain.'),
           z.meta({ examples: ['0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
         ),
+      currency: z
+        .string()
+        .check(
+          z.describe('Monetary denomination represented by this token.'),
+          z.meta({ examples: ['USD'] }),
+        ),
       decimals: z
         .number()
         .check(
@@ -96,29 +104,17 @@ export namespace schema {
     'A normalized token reference for funding quotes.',
   )
 
-  /** Source amount echoed by a funding quote response. */
+  /** Self-contained source or destination amount in a funding quote. */
   export const TokenAmount = Schema.describe(
-    z.object({
-      amount: Schema.DecimalString.check(
-        z.describe("The requested source amount in the token's smallest unit."),
-      ),
-      formatted: z
-        .string()
-        .check(
-          z.describe(
-            'The same amount in human-readable decimal form, using the source token’s `decimals`.',
-          ),
-          z.meta({ examples: ['1'] }),
-        ),
-    }),
-    'The requested source amount in provider-safe base units and display form.',
+    Schema.TokenAmount,
+    'A funding amount in base units and human-readable form.',
   )
 
   /** Provider summary embedded in a funding quote. */
   export const ProviderRef = Schema.describe(
     z.object({
       id: z
-        .enum(['across', 'relay', 'rhino', 'squid'])
+        .enum(['across', 'relay', 'rhino', 'squid', 'symbiosis'])
         .check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
       kind: z
         .string()
@@ -170,7 +166,7 @@ export namespace schema {
     'Machine-readable liquidity, fee, and source signals for a successful quote.',
   )
 
-  /** Provider-derived output, limits, and freshness data. */
+  /** Provider quote freshness data. */
   export const QuoteDetails = Schema.describe(
     z.object({
       expiresAt: z
@@ -179,29 +175,6 @@ export namespace schema {
           z.describe('Timestamp after which the provider quote is no longer valid.'),
           z.meta({ examples: ['2026-01-01T00:01:00Z'] }),
         ),
-      inputAmount: Schema.DecimalString.check(
-        z.describe('Source amount sent to the provider in base units.'),
-        z.meta({ examples: ['1000000'] }),
-      ),
-      minimumOutputAmount: z
-        .optional(Schema.DecimalString)
-        .check(
-          z.describe('Slippage-adjusted minimum destination amount in base units.'),
-          z.meta({ examples: ['988000'] }),
-        ),
-      outputAmount: z
-        .string()
-        .check(z.regex(/^\d+$/))
-        .check(
-          z.describe('Expected destination amount in base units.'),
-          z.meta({ examples: ['989102'] }),
-        ),
-      outputAmountFormatted: z
-        .string()
-        .check(
-          z.describe('Expected destination amount rendered with destination token decimals.'),
-          z.meta({ examples: ['0.989102'] }),
-        ),
       sampledAt: z.iso
         .datetime()
         .check(
@@ -209,12 +182,20 @@ export namespace schema {
           z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
         ),
     }),
-    'Provider-derived output, limits, and freshness data for a funding quote.',
+    'Freshness data for a provider funding quote.',
   )
 
   /** Successful live funding quote. */
   export const FundingQuote = Schema.describe(
     z.object({
+      destinationAmount: TokenAmount.check(z.describe('Expected destination amount.')),
+      destinationAmountMin: z
+        .optional(TokenAmount)
+        .check(
+          z.describe(
+            'Provider-derived minimum destination amount. Symbiosis and Squid quotes use a fixed 1% slippage tolerance.',
+          ),
+        ),
       destinationChain: Chain.check(z.describe('Destination chain, always Tempo mainnet in V1.')),
       destinationToken: Token.check(z.describe('Tempo token expected from this quote.')),
       id: z
@@ -237,7 +218,7 @@ export namespace schema {
   export const Provider = Schema.describe(
     z.object({
       id: z
-        .enum(['across', 'relay', 'rhino', 'squid'])
+        .enum(['across', 'relay', 'rhino', 'squid', 'symbiosis'])
         .check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
       kind: z
         .string()
@@ -285,10 +266,10 @@ export namespace schema {
             z.meta({ examples: ['USDC.e'] }),
           ),
         provider: z
-          .optional(z.enum(['across', 'relay', 'rhino', 'squid']))
+          .optional(z.enum(['across', 'relay', 'rhino', 'squid', 'symbiosis']))
           .check(
             z.describe(
-              'Only request a quote from this provider. Supported ids are `across`, `relay`, `rhino`, and `squid`; omit it to query every configured provider.',
+              'Only request a quote from this provider. Supported ids are `across`, `relay`, `rhino`, `squid`, and `symbiosis`; omit it to query every configured provider.',
             ),
             z.meta({ examples: ['relay'] }),
           ),
@@ -374,7 +355,20 @@ const fundingQuoteResponseExample = (() => {
   return {
     data: [
       {
-        ...candidate,
+        destinationAmount: Value.tokenAmount({
+          baseUnits: '979295',
+          currency: candidate.destinationToken.currency,
+          decimals: candidate.destinationToken.decimals,
+        }),
+        destinationAmountMin: Value.tokenAmount({
+          baseUnits: '939242',
+          currency: candidate.destinationToken.currency,
+          decimals: candidate.destinationToken.decimals,
+        }),
+        destinationChain: candidate.destinationChain,
+        destinationToken: candidate.destinationToken,
+        id: candidate.id,
+        provider: candidate.provider,
         quality: {
           estimatedSeconds: 1,
           liquiditySource: 'providerQuote',
@@ -382,12 +376,15 @@ const fundingQuoteResponseExample = (() => {
           tier: 'liquid',
         },
         quote: {
-          inputAmount: '1000000',
-          minimumOutputAmount: '939242',
-          outputAmount: '979295',
-          outputAmountFormatted: '0.979295',
           sampledAt: '2026-01-01T00:00:00.000Z',
         },
+        sourceAmount: Value.tokenAmount({
+          baseUnits: candidate.sourceAmount.amount,
+          currency: candidate.sourceToken.currency,
+          decimals: candidate.sourceToken.decimals,
+        }),
+        sourceChain: candidate.sourceChain,
+        sourceToken: candidate.sourceToken,
       },
     ],
   }
@@ -416,7 +413,7 @@ export function funding(options: funding.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Returns live quotes for funding Tempo with a stablecoin. Omit `provider` to query all configured providers. This endpoint does not execute a transfer.',
+          'Returns live quotes for funding Tempo with a stablecoin. Omit `provider` to query all configured providers. Provider minimums can use provider-specific slippage policies; Symbiosis and Squid use 1%. This endpoint does not execute a transfer.',
         operationId: 'quoteFunding',
         responses: OpenApi.responses({
           errors: {
@@ -445,6 +442,7 @@ export function funding(options: funding.Options = {}) {
           })
 
         const query = c.req.valid('query')
+        const attempts: FundingQuotes.ProviderAttempt[] = []
         try {
           c.header('Cache-Control', 'no-store')
           return c.json(
@@ -454,6 +452,7 @@ export function funding(options: funding.Options = {}) {
                 adapterTimeoutMs: options.adapterTimeoutMs,
                 cache: { bypass: cacheBypass(c.req.raw) },
                 destinationToken: query.destinationToken,
+                onAttempt: (attempt) => attempts.push(attempt),
                 provider: query.provider,
                 sourceAmount: query.sourceAmount,
                 sourceAmountUnits: query.sourceAmountUnits,
@@ -478,6 +477,9 @@ export function funding(options: funding.Options = {}) {
             })
           }
           throw cause
+        } finally {
+          if (attempts.length > 0)
+            c.set('fundingProviderAttempts', attempts.map(fundingProviderAttempt))
         }
       },
     )
@@ -500,7 +502,7 @@ export function funding(options: funding.Options = {}) {
       }),
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.stable,
-        name: 'tempo-api:funding-chains:v1',
+        name: 'tempo-api:funding-chains:v2',
         key: (c) => c.req.url,
       }),
       (c) => {
@@ -557,6 +559,30 @@ export declare namespace funding {
   }
 }
 
+function fundingProviderAttempt(
+  attempt: FundingQuotes.ProviderAttempt,
+): Log.FundingProviderAttempt {
+  const operation = FundingQuoteProviders.providerOperation(attempt.provider)
+  if (attempt.outcome !== 'failed')
+    return {
+      durationMs: attempt.durationMs,
+      id: attempt.provider,
+      operation,
+      outcome: attempt.outcome,
+    }
+
+  return {
+    durationMs: attempt.durationMs,
+    failure: FundingQuoteProviders.providerFailure({
+      cause: attempt.cause,
+      provider: attempt.provider,
+    }).failure,
+    id: attempt.provider,
+    operation,
+    outcome: attempt.outcome,
+  }
+}
+
 // Maps caller-input errors to a specific 400 message; anything else rethrows.
 function requestErrorMessage(cause: unknown) {
   if (cause instanceof FundingQuotes.InvalidAmountError) return 'Invalid `sourceAmount`.'

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

@@ -1,5 +1,6 @@
 import { Schema } from 'tapimo'
-import { Hex } from 'ox'
+import { FxOracle } from 'tapimo/apps'
+import { Hex, Value as core_Value } from 'ox'
 import { zeroHash } from 'viem'
 
 import * as TestApp from '../../../../test/App.js'
@@ -7,6 +8,16 @@ import * as Runtime from '../../../../test/runtime.js'
 import * as Viem from '../../../../test/Viem.js'
 import * as Receipts from './receipts.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' },
+  }),
+})
+
 /** The decoded `type` names a humanized receipt may report. */
 const transactionTypes = ['legacy', 'eip2930', 'eip1559', 'eip4844', 'eip7702', 'tempo', 'unknown']
 
@@ -40,28 +51,44 @@ describe('GET /transactions/:transactionHash/receipt', () => {
     expect(typeof body.gasUsed).toBe('number')
     expect(Array.isArray(body.logs)).toBe(true)
     // `feeAmount` is the fee charged to the fee payer, derived as
-    // ceil(gasUsed * effectiveGasPrice / 1e12), in the fee token base units.
-    expect(body.feeAmount).toMatch(/^\d+$/)
+    // ceil(gasUsed * effectiveGasPrice / 1e12), in USD base units.
     const expectedFee =
       (BigInt(body.gasUsed) * BigInt(body.effectiveGasPrice) + 10n ** 12n - 1n) / 10n ** 12n
-    expect(body.feeAmount).toBe(expectedFee.toString())
-    // Fee-token metadata is opt-in: the base response must not embed it.
-    expect(body.meta.feeToken).toBeUndefined()
+    expect(body.feeAmount.baseUnits).toBe(expectedFee.toString())
+    expect(body.feeAmount.currency).toBe('USD')
+    expect(body.feeAmount.decimals).toBe(6)
+    expect(body.feeAmount.formatted).toMatch(/^\d+(\.\d+)?$/)
+    // Core fee-token metadata is present by default while the raw address stays
+    // under `meta.rpc`. Curated fields remain opt-in.
+    if (body.meta.rpc.feeToken) {
+      expect(body.feeToken?.address).toBe(body.meta.rpc.feeToken)
+      expect(typeof body.feeToken?.currency).toBe('string')
+      expect(typeof body.feeToken?.decimals).toBe('number')
+      expect(typeof body.feeToken?.name).toBe('string')
+      expect(typeof body.feeToken?.symbol).toBe('string')
+      expect(body.feeToken?.logoUri).toBeUndefined()
+      expect(body.feeToken?.verified).toBeUndefined()
+    } else expect(body.feeToken).toBeUndefined()
+    expect(body.meta).not.toHaveProperty('feeToken')
     // The verbatim JSON-RPC receipt is always available under `meta.rpc`, where
     // `status` is the raw `0x1`/`0x0` flag and gas values stay hex-encoded.
     expect(['0x0', '0x1']).toContain(body.meta.rpc.status)
     expect(body.meta.rpc.gasUsed).toMatch(/^0x[0-9a-f]+$/)
 
-    // include=feeToken: resolved metadata is embedded under meta (best-effort).
+    // Curated fee-token fields are opt-in on the top-level reference.
     const includedResponse = await client.v1.transactions[':transactionHash'].receipt.$get(
-      { param: { transactionHash: transactionHash! }, query: { include: 'feeToken' } },
+      {
+        param: { transactionHash: transactionHash! },
+        query: { include: 'feeToken.logoUri,feeToken.verified' },
+      },
       TestApp.auth,
     )
     const includedBody = await TestApp.json(includedResponse, Receipts.schema.getReceipt.Response)
     expect(includedResponse.status).toBe(200)
-    if (includedBody.feeToken && includedBody.meta?.feeToken) {
-      expect(includedBody.meta.feeToken.address).toBe(includedBody.feeToken)
-      expect(typeof includedBody.meta.feeToken.symbol).toBe('string')
+    if (includedBody.feeToken) {
+      expect(includedBody.feeToken.address).toBe(includedBody.meta.rpc.feeToken)
+      expect(typeof includedBody.feeToken.verified).toBe('boolean')
+      if (includedBody.feeToken.logoUri) expect(typeof includedBody.feeToken.logoUri).toBe('string')
     }
   })
 
@@ -90,7 +117,7 @@ describe('GET /transactions/:transactionHash/receipt', () => {
 })
 
 describe('GET /transactions/receipts', () => {
-  test('returns a humanized receipt page, embedding fee tokens on demand', async () => {
+  test('returns a humanized receipt page with fee-token references', async () => {
     const client = TestApp.client()
     const response = await client.v1.transactions.receipts.$get(
       { query: { limit: '5' } },
@@ -105,6 +132,17 @@ describe('GET /transactions/receipts', () => {
     expect(body.nextCursor === null || typeof body.nextCursor === 'string').toBe(true)
     expect(body.data.length).toBeLessThanOrEqual(5)
 
+    if (body.nextCursor) {
+      const cursorResponse = await client.v1.transactions.receipts.$get(
+        { query: { cursor: body.nextCursor, limit: '5' } },
+        TestApp.auth,
+      )
+      expect(cursorResponse.status).toBe(200)
+      expect(cursorResponse.headers.get('cache-control')).toMatchInlineSnapshot(
+        `"private, max-age=60, stale-while-revalidate=300"`,
+      )
+    }
+
     if (body.data.length > 0) {
       const [receipt] = body.data
       // List rows reuse the detail endpoint's humanized shape: decoded
@@ -115,23 +153,35 @@ describe('GET /transactions/receipts', () => {
       expect(['success', 'reverted']).toContain(receipt!.status)
       expect(transactionTypes).toContain(receipt!.type)
       expect(typeof receipt!.gasUsed).toBe('number')
-      expect(receipt!.feeAmount).toMatch(/^\d+$/)
+      expect(receipt!.feeAmount.baseUnits).toMatch(/^\d+$/)
+      expect(receipt!.feeAmount.currency).toBe('USD')
+      expect(receipt!.feeAmount.decimals).toBe(6)
+      expect(receipt!.feeAmount.formatted).toMatch(/^\d+(\.\d+)?$/)
       expect(receipt!.meta.rpc.status).toMatch(/^0x[0-9a-f]+$/)
-      // Fee-token metadata is opt-in: the base response must not embed it.
-      expect(receipt!.meta.feeToken).toBeUndefined()
+      if (receipt!.meta.rpc.feeToken) {
+        expect(receipt!.feeToken?.address).toBe(receipt!.meta.rpc.feeToken)
+        expect(typeof receipt!.feeToken?.currency).toBe('string')
+        expect(typeof receipt!.feeToken?.decimals).toBe('number')
+        expect(typeof receipt!.feeToken?.name).toBe('string')
+        expect(typeof receipt!.feeToken?.symbol).toBe('string')
+        expect(receipt!.feeToken?.logoUri).toBeUndefined()
+        expect(receipt!.feeToken?.verified).toBeUndefined()
+      } else expect(receipt!.feeToken).toBeUndefined()
+      expect(receipt!.meta).not.toHaveProperty('feeToken')
     }
 
     const includedResponse = await client.v1.transactions.receipts.$get(
-      { query: { limit: '5', include: 'feeToken' } },
+      { query: { limit: '5', include: 'feeToken.logoUri,feeToken.verified' } },
       TestApp.auth,
     )
     const includedBody = await TestApp.json(includedResponse, Receipts.schema.getReceipts.Response)
     expect(includedResponse.status).toBe(200)
-    const withFeeToken = includedBody.data.find((receipt) => receipt.meta?.feeToken)
+    const withFeeToken = includedBody.data.find((receipt) => receipt.feeToken)
     if (withFeeToken) {
-      // When metadata resolves, it must describe the receipt's fee token.
-      expect(withFeeToken.meta.feeToken!.address).toBe(withFeeToken.feeToken)
-      expect(typeof withFeeToken.meta.feeToken!.symbol).toBe('string')
+      expect(withFeeToken.feeToken!.address).toBe(withFeeToken.meta.rpc.feeToken)
+      expect(typeof withFeeToken.feeToken!.verified).toBe('boolean')
+      if (withFeeToken.feeToken!.logoUri)
+        expect(typeof withFeeToken.feeToken!.logoUri).toBe('string')
     }
   })
 
@@ -149,10 +199,39 @@ describe('GET /transactions/receipts', () => {
     expect(body.error.code).toBe('query_invalid')
   })
 
+  test('values the fee in a requested denomination', async () => {
+    expect(transactionHash).toBeDefined()
+    const client = TestApp.client({ fx: { oracle: fixed } })
+
+    // Denominations are case-insensitive.
+    const response = await client.v1.transactions[':transactionHash'].receipt.$get(
+      { param: { transactionHash: transactionHash! }, query: { denomination: 'aud' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Receipts.schema.getReceipt.Response)
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toMatchInlineSnapshot(
+      `"private, max-age=60, stale-while-revalidate=300"`,
+    )
+    // USD -> AUD at the fixed 1.6 cross rate, floored to 6 dp.
+    expect(body.feeAmount.valuation).toEqual({
+      amount: core_Value.format((BigInt(body.feeAmount.baseUnits) * 16n) / 10n, 6),
+      currency: 'AUD',
+    })
+    expect(body.meta.pricing).toMatchInlineSnapshot(`
+      {
+        "asOf": "2026-01-01T00:00:00.000Z",
+        "basis": "nominal",
+        "source": "fixed",
+      }
+    `)
+  })
+
   test('rejects the transactions-only include=receipt member', async () => {
     // `receipt` is a transactions-list embed; the receipts endpoints own their
-    // own `include` enum (`feeToken` only) and must reject it. The typed client
-    // would refuse the literal, so exercise the validator via `app.request`.
+    // own include enum and must reject it. The typed client would refuse the
+    // literal, so exercise the validator via `app.request`.
     const response = await TestApp.create().request('/v1/transactions/receipts?include=receipt', {
       headers: { authorization: `Bearer ${TestApp.key.token}` },
     })
@@ -161,6 +240,25 @@ describe('GET /transactions/receipts', () => {
     expect(body.error.code).toBe('query_invalid')
   })
 
+  test('rejects the legacy include=feeToken member', async () => {
+    const response = await TestApp.create().request('/v1/transactions/receipts?include=feeToken', {
+      headers: { authorization: `Bearer ${TestApp.key.token}` },
+    })
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(400)
+    expect(body.error.code).toBe('query_invalid')
+  })
+
+  test('rejects generic token fields', async () => {
+    const response = await TestApp.create().request(
+      '/v1/transactions/receipts?include=token.logoUri',
+      { headers: { authorization: `Bearer ${TestApp.key.token}` } },
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    expect(response.status).toBe(400)
+    expect(body.error.code).toBe('query_invalid')
+  })
+
   test('narrows receipts by execution status', async () => {
     const client = TestApp.client()
     const response = await client.v1.transactions.receipts.$get(
@@ -193,7 +291,15 @@ describe('GET /transactions/receipts', () => {
     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)
+    // Fees are USD, so the default denomination values them at identity with
+    // no rate provenance.
+    for (const receipt of body.data)
+      expect(receipt.feeAmount.valuation).toEqual({
+        amount: receipt.feeAmount.formatted,
+        currency: 'USD',
+      })
+    expect(body.meta!.pricing).toBeUndefined()
 
     // Without `include=totalCount`, the same page omits `meta` and the count.
     const bare = await client.v1.transactions.receipts.$get(