tapimo 0.4.3 → 0.5.0

package/src/apps/data/FundingQuoteProviders.ts

@@ -0,0 +1,251 @@
+import * as FundingQuotes from '../../internal/FundingQuotes.js'
+
+type Fetch = typeof globalThis.fetch
+
+const defaultFetch: Fetch = (input, init) => globalThis.fetch(input, init)
+
+const defaultRelayBaseUrl = 'https://api.relay.link'
+
+/** Creates the live funding quote adapters configured for this deployment. */
+export function createAdapters(options: createAdapters.Options = {}) {
+  return (
+    options.relay ? { relay: relay(options.relay) } : {}
+  ) satisfies FundingQuotes.ProviderAdapters
+}
+
+export declare namespace createAdapters {
+  /** Provider adapter factory options. Omit a provider to leave it unconfigured. */
+  type Options = {
+    /** Relay quote adapter options. */
+    relay?: relay.Options | false | undefined
+  }
+}
+
+/** Creates a Relay quote adapter backed by `/quote/v2`. */
+export function relay(options: relay.Options): FundingQuotes.ProviderAdapter {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultRelayBaseUrl)
+  const fetcher = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+
+  return {
+    async probeQuote({ candidate }, signal) {
+      const originChainId = providerChainId(candidate.sourceChain, 'relay')
+      const destinationChainId = eip155ChainId(candidate.destinationChain)
+      const headers = relayHeaders(options.apiKey)
+
+      try {
+        const quote = await requestJson(new URL(`${baseUrl}/quote/v2`), {
+          body: {
+            amount: candidate.sourceAmount.amount,
+            destinationChainId: Number(destinationChainId),
+            destinationCurrency: candidate.destinationToken.address,
+            originChainId: Number(originChainId),
+            originCurrency: candidate.sourceToken.address,
+            recipient: options.recipientAddress ?? options.userAddress,
+            tradeType: 'EXACT_INPUT',
+            user: options.userAddress,
+          },
+          fetcher,
+          headers,
+          method: 'POST',
+          signal,
+        })
+        return formatRelayResult(candidate, quote, now())
+      } catch (cause) {
+        const unavailable = providerUnavailable(cause, [
+          'NO_QUOTES',
+          'NO_ROUTE',
+          'UNSUPPORTED_ROUTE',
+        ])
+        if (!unavailable) throw cause
+        return unavailableResult({
+          detail: 'relay:quote-v2',
+          message: unavailable,
+          now: now(),
+          source: 'providerQuote',
+        })
+      }
+    },
+  }
+}
+
+export declare namespace relay {
+  /** Relay quote adapter options. */
+  type Options = {
+    /** Probe wallet address required by Relay's quote API. */
+    userAddress: string
+    /** Optional recipient override; defaults to `userAddress`. */
+    recipientAddress?: string | undefined
+    /** Optional Relay API key for higher rate limits. */
+    apiKey?: string | undefined
+    /** Override for tests or Relay testnet environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: Fetch | undefined
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+  }
+}
+
+function formatRelayResult(
+  candidate: FundingQuotes.QuoteCandidate,
+  quote: unknown,
+  now: Date,
+): FundingQuotes.QuoteProbeResult {
+  const details = record(record(quote)['details'])
+  const currencyOut = record(details['currencyOut'])
+  const outputAmount = decimalString(currencyOut['amount'])
+  const status = outputAmount
+    ? { status: 'available' as const, tier: 'liquid' as const }
+    : { status: 'unknown' as const, tier: 'unknown' as const }
+
+  return {
+    minimumOutputAmount: decimalString(currencyOut['minimumAmount']),
+    outputAmount,
+    outputAmountFormatted: outputAmount
+      ? decimalFromBaseUnits(outputAmount, candidate.destinationToken.decimals)
+      : undefined,
+    quality: {
+      estimatedSeconds: nonnegativeInteger(details['timeEstimate']),
+      liquiditySource: 'providerQuote',
+      sourceDetail: 'relay:quote-v2',
+      tier: status.tier,
+    },
+    sampledAt: now.toISOString(),
+    status: status.status,
+  }
+}
+
+function unavailableResult(options: {
+  detail: string
+  message: string
+  now: Date
+  source: string
+}): FundingQuotes.QuoteProbeResult {
+  return {
+    quality: {
+      liquiditySource: options.source,
+      sourceDetail: `${options.detail}:${options.message}`,
+      tier: 'unavailable',
+    },
+    sampledAt: options.now.toISOString(),
+    status: 'unavailable',
+  }
+}
+
+async function requestJson(
+  url: URL,
+  options: {
+    body?: unknown
+    fetcher: Fetch
+    headers?: Record<string, string> | undefined
+    method?: string | undefined
+    signal: AbortSignal
+  },
+) {
+  const headers = { accept: 'application/json', ...options.headers }
+  const init: RequestInit = {
+    headers:
+      options.body === undefined ? headers : { ...headers, 'content-type': 'application/json' },
+    method: options.method ?? 'GET',
+    signal: options.signal,
+  }
+  if (options.body !== undefined) init.body = JSON.stringify(options.body)
+  const response = await options.fetcher(url, init)
+  const text = await response.text()
+  const body = parseJson(text)
+  if (!response.ok) throw new ProviderResponseError(response.status, body)
+  return body
+}
+
+function relayHeaders(apiKey: string | undefined): Record<string, string> | undefined {
+  return apiKey ? { 'x-api-key': apiKey } : undefined
+}
+
+function providerUnavailable(cause: unknown, codes: readonly string[]) {
+  if (!(cause instanceof ProviderResponseError) || cause.status < 400 || cause.status >= 500)
+    return undefined
+  const code = providerErrorCode(cause.body)
+  if (code && codes.includes(code)) return code
+  return undefined
+}
+
+function providerErrorCode(input: unknown) {
+  const body = record(input)
+  const code = stringValue(body['code']) ?? stringValue(body['errorCode'])
+  return code && /^[A-Za-z0-9_.:-]{1,64}$/.test(code) ? code : undefined
+}
+
+function providerChainId(
+  quoteChain: FundingQuotes.QuoteCandidate['sourceChain'],
+  provider: string,
+) {
+  const providerIds = quoteChain.providerIds as Record<string, string> | undefined
+  const id = providerIds?.[provider]
+  if (id && /^\d+$/.test(id)) return id
+  return eip155ChainId(quoteChain)
+}
+
+function eip155ChainId(chain: { id: string; kind: string }) {
+  if (chain.kind !== 'evm') throw new UnsupportedProviderChainError()
+  const match = /^eip155:(\d+)$/.exec(chain.id)
+  if (!match?.[1]) throw new UnsupportedProviderChainError()
+  return match[1]
+}
+
+function normalizeBaseUrl(input: string) {
+  return input.replace(/\/+$/, '')
+}
+
+function parseJson(input: string) {
+  if (!input) return null
+  try {
+    return JSON.parse(input) as unknown
+  } catch {
+    return input
+  }
+}
+
+function record(input: unknown): Record<string, unknown> {
+  return input && typeof input === 'object' && !Array.isArray(input)
+    ? (input as Record<string, unknown>)
+    : {}
+}
+
+function stringValue(input: unknown) {
+  return typeof input === 'string' && input.length > 0 ? input : undefined
+}
+
+function decimalString(input: unknown) {
+  if (typeof input === 'string' && /^\d+(\.\d+)?$/.test(input)) return input
+  if (typeof input === 'number' && Number.isFinite(input) && input >= 0) return String(input)
+  return undefined
+}
+
+function nonnegativeInteger(input: unknown) {
+  if (typeof input === 'number' && Number.isSafeInteger(input) && input >= 0) return input
+  if (typeof input === 'string' && /^\d+$/.test(input)) return Number(input)
+  return undefined
+}
+
+function decimalFromBaseUnits(baseUnits: string, decimals: number) {
+  const padded = baseUnits.padStart(decimals + 1, '0')
+  const whole = decimals === 0 ? padded : padded.slice(0, -decimals)
+  const fraction = decimals === 0 ? '' : padded.slice(-decimals).replace(/0+$/, '')
+  return fraction ? `${whole}.${fraction}` : whole
+}
+
+class ProviderResponseError extends Error {
+  override name = 'FundingQuoteProviders.ProviderResponseError'
+
+  constructor(
+    readonly status: number,
+    readonly body: unknown,
+  ) {
+    super(`Provider request failed with status ${status}`)
+  }
+}
+
+class UnsupportedProviderChainError extends Error {
+  override name = 'FundingQuoteProviders.UnsupportedProviderChainError'
+}

package/src/apps/data/index.ts

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

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

@@ -1,8 +1,10 @@
 import { Schema } from 'tapimo'
 import { Value as core_Value } from 'ox'
+import { Actions } from 'viem/tempo'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
+import * as TestViem from '../../../../test/Viem.js'
 import * as Balances from './balances.js'
 import * as Tokens from './tokens.js'
 
@@ -45,7 +47,7 @@ describe('GET /addresses/:address/balances', () => {
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
 
     expect(response.status).toBe(200)
-    expect(response.headers.get('server-timing')?.includes('address_balances;dur=')).toBe(true)
+    expect(response.headers.get('server-timing')?.includes('balances_discovery;dur=')).toBe(true)
     expect(Array.isArray(body.data)).toBe(true)
     expect(body.data.length).toBeLessThanOrEqual(5)
     // Pagination fields stay at the response root; cursor pagination has no
@@ -72,16 +74,48 @@ describe('GET /addresses/:address/balances', () => {
       ),
     ).toBe(true)
     // Results are restricted to TIP-20 tokens (deterministic `0x20c0…` factory
-    // addresses), so non-TIP-20 contracts in `token_balances_snapshot` are
-    // excluded.
+    // addresses), so non-TIP-20 contracts in the delta history are excluded.
     expect(body.data.every((entry) => entry.token.address.startsWith('0x20c0'))).toBe(true)
     // Amounts are returned largest-first.
     const amounts = body.data.map((entry) => BigInt(entry.amount))
     expect(amounts.every((amount, index) => index === 0 || amounts[index - 1]! >= amount)).toBe(
       true,
     )
+
+    const rpc = TestViem.getClient()
+    const current = await Promise.all(
+      body.data.map((entry) =>
+        Actions.token.getBalance(rpc, { account: holder, token: entry.token.address }),
+      ),
+    )
+    expect(body.data.map((entry) => entry.amount)).toEqual(
+      current.map((balance) => balance.amount.toString()),
+    )
   })
 
+  test.skipIf(runtime.mode !== 'localnet')(
+    'discovers freshly transferred assets from deltas',
+    async () => {
+      const fixture = runtime.fixtures?.crossTokenTransfer
+      if (!fixture) throw new Error('expected cross-token transfer fixture')
+      const client = app()
+
+      const response = await client.v1.addresses[':address'].balances.$get(
+        { param: { address: fixture.recipient }, query: { limit: '5' } },
+        TestApp.auth,
+      )
+      const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+
+      expect(response.status).toBe(200)
+      expect(body.data).toContainEqual(
+        expect.objectContaining({
+          amount: '1000000',
+          id: fixture.destinationToken,
+        }),
+      )
+    },
+  )
+
   test('embeds an exact balance total on demand via include=totalCount', async () => {
     const client = app()
     const holder = await holderWithBalance(client)
@@ -93,15 +127,14 @@ describe('GET /addresses/:address/balances', () => {
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
 
     expect(response.status).toBe(200)
-    expect(response.headers.get('server-timing')?.includes('address_balances_count;dur=')).toBe(
-      true,
-    )
+    expect(response.headers.get('server-timing')?.includes('balances_discovery;dur=')).toBe(true)
     expect(Number.isInteger(body.meta?.totalCount)).toBe(true)
     expect(body.meta!.totalCount).toBeGreaterThanOrEqual(body.data.length)
-    // The count is sort-key-pruned on ClickHouse, so it is exact (never capped).
+    // The count comes from the corrected candidate set and is never capped.
     expect(body.meta!.totalCountCapped).toBe(false)
 
-    // Without the include, `meta` is omitted and no count query runs.
+    // Without the include, `meta` is omitted. The corrected candidate set
+    // already supplies the count, so no second indexer query is needed.
     const bareResponse = await client.v1.addresses[':address'].balances.$get(
       { param: { address: holder }, query: { limit: '5' } },
       TestApp.auth,
@@ -109,8 +142,8 @@ describe('GET /addresses/:address/balances', () => {
     const bare = await TestApp.json(bareResponse, Balances.schema.getAddressBalances.Response)
     expect(bareResponse.status).toBe(200)
     expect(bare.meta).toBeUndefined()
-    expect(bareResponse.headers.get('server-timing')?.includes('address_balances_count;dur=')).toBe(
-      false,
+    expect(bareResponse.headers.get('server-timing')?.includes('balances_discovery;dur=')).toBe(
+      true,
     )
   })
 
@@ -138,6 +171,27 @@ describe('GET /addresses/:address/balances', () => {
     `)
   })
 
+  test('surfaces a 502 when RPC correction is unavailable', async () => {
+    const client = app({ rpc: { url: () => 'http://127.0.0.1:1' } })
+    const holder = await holderWithBalance(client)
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    const { requestId, error } = body
+    const { message, ...stableError } = error
+
+    expect(response.status).toMatchInlineSnapshot(`502`)
+    expect(typeof requestId).toMatchInlineSnapshot(`"string"`)
+    expect(typeof message).toMatchInlineSnapshot(`"string"`)
+    expect(stableError).toMatchInlineSnapshot(`
+      {
+        "code": "upstream_error",
+      }
+    `)
+  })
+
   test('rejects invalid account addresses', async () => {
     // The typed client requires `address: `Hex.Hex`` so an invalid literal
     // cannot pass through it; exercise the validator via `app.request`.
@@ -250,14 +304,6 @@ describe('GET /addresses/:address/balances', () => {
       },
       TestApp.auth,
     )
-    if (runtime.mode === 'testnet' && response.status === 502) {
-      // Hosted TIDX can intermittently reject this live filtered balance query
-      // with a 422. Localnet still exercises the behavior strictly; on testnet,
-      // accept the documented upstream-error envelope instead of flaking CI.
-      const body = await TestApp.json(response, Schema.ErrorResponse)
-      expect(body.error.code).toBe('upstream_error')
-      return
-    }
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
     expect(response.status).toBe(200)