tapimo 0.5.3 → 0.7.0

package/src/apps/data/FundingQuoteProviders.ts

@@ -1,6 +1,7 @@
 import * as z from 'zod/mini'
 
 import * as FundingQuotes from '../../internal/FundingQuotes.js'
+import * as Store from '../../internal/Store.js'
 
 type Fetch = typeof globalThis.fetch
 
@@ -10,13 +11,23 @@ const defaultAcrossBaseUrl = 'https://app.across.to/api'
 const defaultRelayBaseUrl = 'https://api.relay.link'
 const defaultRhinoBaseUrl = 'https://api.rhino.fi/bridge'
 const defaultSquidBaseUrl = 'https://v2.api.squidrouter.com/v2'
+const defaultSymbiosisBaseUrl = 'https://api.symbiosis.finance/crosschain'
+// Keep one upstream slot free for deployment smoke tests and operational probes.
+const symbiosisRateLimit = 4
+const symbiosisRateLimitWindowMs = 1_000
 const providerOperations = {
   across: 'swap/approval',
   relay: 'quote/v2',
   rhino: 'quote/bridge-swap/public',
   squid: 'v2/route',
+  symbiosis: 'v2/quote',
 } as const
 
+/** Returns the stable upstream operation used by a funding quote provider. */
+export function providerOperation(provider: FundingQuotes.ProviderId) {
+  return providerOperations[provider]
+}
+
 namespace schema {
   const IntegerString = z.string().check(z.regex(/^\d+$/))
 
@@ -65,6 +76,30 @@ namespace schema {
       }),
     }),
   })
+
+  export const SymbiosisToken = z.object({
+    address: z.string(),
+    chainId: z.number().check(z.int(), z.nonnegative()),
+    decimals: z.number().check(z.int(), z.nonnegative()),
+  })
+
+  const SymbiosisTokenAmount = z.extend(SymbiosisToken, { amount: IntegerString })
+
+  export const SymbiosisQuote = z.object({
+    estimatedTime: z.optional(z.number().check(z.nonnegative())),
+    kind: z.union([z.literal('bridge'), z.literal('crosschain-swap'), z.literal('intent-swap')]),
+    routes: z
+      .array(
+        z.object({
+          tokens: z.array(SymbiosisToken).check(z.minLength(1)),
+        }),
+      )
+      .check(z.minLength(1)),
+    tokenAmountOut: SymbiosisTokenAmount,
+    tokenAmountOutMin: SymbiosisTokenAmount,
+    tx: z.object({ chainId: z.number().check(z.int(), z.nonnegative()) }),
+    type: z.union([z.literal('evm'), z.literal('tron')]),
+  })
 }
 
 /** Creates the live funding quote adapters configured for this deployment. */
@@ -74,6 +109,7 @@ export function createAdapters(options: createAdapters.Options = {}) {
     ...(options.relay ? { relay: relay(options.relay) } : {}),
     ...(options.rhino ? { rhino: rhino(options.rhino) } : {}),
     ...(options.squid ? { squid: squid(options.squid) } : {}),
+    ...(options.symbiosis ? { symbiosis: symbiosis(options.symbiosis) } : {}),
   } satisfies FundingQuotes.ProviderAdapters
 }
 
@@ -88,6 +124,8 @@ export declare namespace createAdapters {
     rhino?: rhino.Options | false | undefined
     /** Squid quote adapter options. */
     squid?: squid.Options | false | undefined
+    /** Symbiosis quote adapter options. */
+    symbiosis?: symbiosis.Options | false | undefined
   }
 }
 
@@ -137,6 +175,22 @@ export declare namespace configureSquid {
   }
 }
 
+/** Resolves Symbiosis deployment configuration. */
+export function configureSymbiosis(
+  options: configureSymbiosis.Options = {},
+): symbiosis.Options | undefined {
+  if (!options.userAddress) return undefined
+  return { userAddress: options.userAddress }
+}
+
+export declare namespace configureSymbiosis {
+  /** Optional deployment binding required to enable Symbiosis. */
+  type Options = {
+    /** Symbiosis quote-user binding. */
+    userAddress?: string | undefined
+  }
+}
+
 /** Creates an Across quote adapter backed by `/swap/approval`. */
 export function across(options: across.Options): FundingQuotes.ProviderAdapter {
   assertAcrossConfiguration(options)
@@ -238,7 +292,7 @@ export function relay(options: relay.Options): FundingQuotes.ProviderAdapter {
           method: 'POST',
           signal,
         })
-        return formatRelayResult(candidate, quote, now())
+        return formatRelayResult(quote, now())
       } catch (cause) {
         const unavailable = providerUnavailable(cause, [
           'NO_QUOTES',
@@ -397,9 +451,87 @@ export declare namespace squid {
   }
 }
 
+/** Creates a Symbiosis quote adapter backed by `/v2/quote`. */
+export function symbiosis(options: symbiosis.Options): FundingQuotes.ProviderAdapter {
+  assertUserAddress(options.userAddress)
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultSymbiosisBaseUrl)
+  const fetcher = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+  const rateLimitStore = options.rateLimitStore ?? Store.memory()
+
+  return {
+    async probeQuote({ candidate }, signal) {
+      const fromChainId = Number(providerChainId(candidate.sourceChain, 'symbiosis'))
+      const fromToken = symbiosisSourceToken(candidate.sourceChain, candidate.sourceToken)
+      const toChainId = Number(eip155ChainId(candidate.destinationChain))
+
+      try {
+        await consumeSymbiosisQuota(rateLimitStore, now())
+        const quote = await requestJson(new URL(`${baseUrl}/v2/quote`), {
+          body: {
+            from: options.userAddress,
+            slippage: 100,
+            to: options.userAddress,
+            tokenAmountIn: {
+              address: fromToken,
+              amount: candidate.sourceAmount.amount,
+              chainId: fromChainId,
+              decimals: candidate.sourceToken.decimals,
+              symbol: candidate.sourceToken.symbol,
+            },
+            tokenOut: {
+              address: candidate.destinationToken.address,
+              chainId: toChainId,
+              decimals: candidate.destinationToken.decimals,
+              symbol: candidate.destinationToken.symbol,
+            },
+          },
+          fetcher,
+          headers: { 'x-partner-id': 'tempo' },
+          method: 'POST',
+          signal,
+        })
+        return formatSymbiosisResult(candidate, quote, now())
+      } catch (cause) {
+        const unavailable =
+          providerUnavailable(cause, [
+            'AMOUNT_TOO_LOW',
+            'NO_ROUTE',
+            'NO_ROUTE_FOUND',
+            'ROUTE_NOT_FOUND',
+            'UNSUPPORTED_ROUTE',
+          ]) ?? symbiosisUnavailable(cause)
+        if (!unavailable) throw cause
+        return unavailableResult({
+          detail: 'symbiosis:quote-v2',
+          message: unavailable,
+          now: now(),
+          source: 'providerQuote',
+        })
+      }
+    },
+  }
+}
+
+export declare namespace symbiosis {
+  /** Symbiosis quote adapter options. */
+  type Options = {
+    /** Override for tests or Symbiosis test environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: Fetch | undefined
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+    /** Atomic store used to enforce the provider-wide quote quota. */
+    rateLimitStore?: Store.Store | undefined
+    /** Probe wallet address used as the Symbiosis sender and recipient. */
+    userAddress: string
+  }
+}
+
 /** Returns bounded provider failure details suitable for structured request logs. */
 export function providerFailure(options: providerFailure.Options): providerFailure.Result {
-  const operation = providerOperations[options.provider]
+  const operation = providerOperation(options.provider)
   if (
     options.cause instanceof FundingQuotes.ProviderAdapterTimeoutError ||
     (options.cause instanceof DOMException && options.cause.name === 'AbortError')
@@ -417,6 +549,8 @@ export function providerFailure(options: providerFailure.Options): providerFailu
   }
   if (options.cause instanceof ProviderPayloadError)
     return { failure: 'payload', id: options.provider, operation }
+  if (options.cause instanceof ProviderRateLimitError)
+    return { failure: 'rate_limit', id: options.provider, operation }
   if (options.cause instanceof TypeError)
     return { failure: 'network', id: options.provider, operation }
   return { failure: 'unknown', id: options.provider, operation }
@@ -431,7 +565,7 @@ export declare namespace providerFailure {
     /** Stable provider error code, when one is safe to retain. */
     code?: string | undefined
     /** Failure boundary that rejected the provider request. */
-    failure: 'http' | 'network' | 'payload' | 'timeout' | 'unknown'
+    failure: 'http' | 'network' | 'payload' | 'rate_limit' | 'timeout' | 'unknown'
     /** Provider identifier. */
     id: FundingQuotes.ProviderId
     /** Provider operation identifier. */
@@ -466,10 +600,6 @@ function formatAcrossResult(
     expiresAt: expiresAt.toISOString(),
     minimumOutputAmount: response.minOutputAmount,
     outputAmount: response.expectedOutputAmount,
-    outputAmountFormatted: decimalFromBaseUnits(
-      response.expectedOutputAmount,
-      candidate.destinationToken.decimals,
-    ),
     quality: {
       estimatedSeconds: response.expectedFillTime,
       liquiditySource: 'providerQuote',
@@ -481,11 +611,7 @@ function formatAcrossResult(
   }
 }
 
-function formatRelayResult(
-  candidate: FundingQuotes.QuoteCandidate,
-  quote: unknown,
-  now: Date,
-): FundingQuotes.QuoteProbeResult {
+function formatRelayResult(quote: unknown, now: Date): FundingQuotes.QuoteProbeResult {
   const details = record(record(quote)['details'])
   const currencyOut = record(details['currencyOut'])
   const outputAmount = decimalString(currencyOut['amount'])
@@ -496,9 +622,6 @@ function formatRelayResult(
   return {
     minimumOutputAmount: decimalString(currencyOut['minimumAmount']),
     outputAmount,
-    outputAmountFormatted: outputAmount
-      ? decimalFromBaseUnits(outputAmount, candidate.destinationToken.decimals)
-      : undefined,
     quality: {
       estimatedSeconds: nonnegativeInteger(details['timeEstimate']),
       liquiditySource: 'providerQuote',
@@ -535,7 +658,6 @@ function formatRhinoResult(
 
   return {
     outputAmount,
-    outputAmountFormatted: decimalFromBaseUnits(outputAmount, candidate.destinationToken.decimals),
     quality: {
       ...(response.estimatedDuration === undefined || response.estimatedDuration === null
         ? {}
@@ -570,10 +692,6 @@ function formatSquidResult(
   return {
     minimumOutputAmount: response.toAmountMin,
     outputAmount: response.toAmount,
-    outputAmountFormatted: decimalFromBaseUnits(
-      response.toAmount,
-      candidate.destinationToken.decimals,
-    ),
     quality: {
       estimatedSeconds: Math.ceil(response.estimatedRouteDuration),
       liquiditySource: 'providerQuote',
@@ -585,6 +703,64 @@ function formatSquidResult(
   }
 }
 
+function formatSymbiosisResult(
+  candidate: FundingQuotes.QuoteCandidate,
+  quote: unknown,
+  now: Date,
+): FundingQuotes.QuoteProbeResult {
+  const parsed = schema.SymbiosisQuote.safeParse(quote)
+  if (!parsed.success) throw new ProviderPayloadError()
+  const response = parsed.data
+  const sourceChainId = Number(providerChainId(candidate.sourceChain, 'symbiosis'))
+  const sourceToken = symbiosisSourceToken(candidate.sourceChain, candidate.sourceToken)
+  const firstToken = response.routes[0]!.tokens[0]!
+  const lastRoute = response.routes[response.routes.length - 1]!
+  const lastToken = lastRoute.tokens[lastRoute.tokens.length - 1]!
+  if (
+    response.tx.chainId !== sourceChainId ||
+    response.type !== candidate.sourceChain.kind ||
+    !matchesSymbiosisToken(firstToken, {
+      address: sourceToken,
+      chainId: sourceChainId,
+      decimals: candidate.sourceToken.decimals,
+    }) ||
+    !matchesSymbiosisToken(lastToken, {
+      address: candidate.destinationToken.address,
+      chainId: Number(eip155ChainId(candidate.destinationChain)),
+      decimals: candidate.destinationToken.decimals,
+    }) ||
+    !matchesSymbiosisToken(response.tokenAmountOut, {
+      address: candidate.destinationToken.address,
+      chainId: Number(eip155ChainId(candidate.destinationChain)),
+      decimals: candidate.destinationToken.decimals,
+    }) ||
+    !matchesSymbiosisToken(response.tokenAmountOutMin, {
+      address: candidate.destinationToken.address,
+      chainId: Number(eip155ChainId(candidate.destinationChain)),
+      decimals: candidate.destinationToken.decimals,
+    }) ||
+    BigInt(response.tokenAmountOut.amount) <= 0n ||
+    BigInt(response.tokenAmountOutMin.amount) <= 0n ||
+    BigInt(response.tokenAmountOutMin.amount) > BigInt(response.tokenAmountOut.amount)
+  )
+    throw new ProviderPayloadError()
+
+  return {
+    minimumOutputAmount: response.tokenAmountOutMin.amount,
+    outputAmount: response.tokenAmountOut.amount,
+    quality: {
+      ...(response.estimatedTime === undefined
+        ? {}
+        : { estimatedSeconds: Math.ceil(response.estimatedTime) }),
+      liquiditySource: 'providerQuote',
+      sourceDetail: 'symbiosis:quote-v2',
+      tier: 'liquid',
+    },
+    sampledAt: now.toISOString(),
+    status: 'available',
+  }
+}
+
 function unavailableResult(options: {
   detail: string
   message: string
@@ -664,6 +840,22 @@ function squidUnavailable(cause: unknown) {
   return undefined
 }
 
+function symbiosisUnavailable(cause: unknown) {
+  if (!(cause instanceof ProviderResponseError) || cause.status !== 400) return undefined
+  const body = record(cause.body)
+  if (body['message'] === 'Amount is too low to cover fees') return 'AMOUNT_TOO_LOW'
+  return undefined
+}
+
+async function consumeSymbiosisQuota(store: Store.Store, now: Date) {
+  const time = now.getTime()
+  const bucket = Math.floor(time / symbiosisRateLimitWindowMs)
+  const count = await Store.increment(store, `funding:symbiosis:quote:${bucket}`, {
+    ttl: symbiosisRateLimitWindowMs * 2,
+  })
+  if (count > symbiosisRateLimit) throw new ProviderRateLimitError()
+}
+
 function providerChainId(
   quoteChain: FundingQuotes.QuoteCandidate['sourceChain'],
   provider: string,
@@ -694,6 +886,16 @@ function rhinoToken(token: FundingQuotes.TokenRef) {
   return id
 }
 
+function symbiosisSourceToken(chain: FundingQuotes.ChainRef, token: FundingQuotes.TokenRef) {
+  if (chain.kind !== 'tron') return token.address
+  const tokens: Record<string, string> = {
+    TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t: '0xa614f803b6fd780986a42c78ec9c7f77e6ded13c',
+  }
+  const id = tokens[token.address]
+  if (!id) throw new UnsupportedProviderTokenError()
+  return id
+}
+
 function matchesToken(
   token: z.output<typeof schema.AcrossQuote>['inputToken'],
   chain: FundingQuotes.ChainRef,
@@ -718,6 +920,29 @@ function matchesSquidToken(
   )
 }
 
+function matchesSymbiosisToken(
+  token: z.output<typeof schema.SymbiosisToken>,
+  options: matchesSymbiosisToken.Options,
+) {
+  return (
+    token.address.toLowerCase() === options.address.toLowerCase() &&
+    token.chainId === options.chainId &&
+    token.decimals === options.decimals
+  )
+}
+
+declare namespace matchesSymbiosisToken {
+  /** Expected provider token identity. */
+  type Options = {
+    /** Provider-specific token address. */
+    address: string
+    /** Provider-specific chain id. */
+    chainId: number
+    /** Token decimal precision. */
+    decimals: number
+  }
+}
+
 function eip155ChainId(chain: { id: string; kind: string }) {
   if (chain.kind !== 'evm') throw new UnsupportedProviderChainError()
   const match = /^eip155:(\d+)$/.exec(chain.id)
@@ -760,13 +985,6 @@ function nonnegativeInteger(input: unknown) {
   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
-}
-
 function baseUnitsFromDecimal(value: string, decimals: number) {
   if (!/^\d+(\.\d+)?$/.test(value)) return undefined
   const [whole, fraction = ''] = value.split('.')
@@ -785,8 +1003,12 @@ function assertAcrossConfiguration(options: across.Options) {
 }
 
 function assertSquidConfiguration(options: squid.Options) {
-  if (options.integratorId.length === 0 || !/^0x[\da-fA-F]{40}$/.test(options.userAddress))
-    throw new ProviderConfigurationError()
+  if (options.integratorId.length === 0) throw new ProviderConfigurationError()
+  assertUserAddress(options.userAddress)
+}
+
+function assertUserAddress(userAddress: string) {
+  if (!/^0x[\da-fA-F]{40}$/.test(userAddress)) throw new ProviderConfigurationError()
 }
 
 class ProviderConfigurationError extends Error {
@@ -797,6 +1019,10 @@ class ProviderPayloadError extends Error {
   override name = 'FundingQuoteProviders.ProviderPayloadError'
 }
 
+class ProviderRateLimitError extends Error {
+  override name = 'FundingQuoteProviders.ProviderRateLimitError'
+}
+
 class ProviderResponseError extends Error {
   override name = 'FundingQuoteProviders.ProviderResponseError'
 

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

@@ -0,0 +1,118 @@
+import * as FxOracle from './FxOracle.js'
+
+const set = {
+  asOf: '2026-01-01T00:00:00.000Z',
+  base: 'EUR',
+  rates: { AUD: '1.6', USD: '1.25' },
+} satisfies FxOracle.RateSet
+
+function feedUrl(usd: string) {
+  const body = `<Envelope><Cube><Cube time="2026-01-01"><Cube currency="AUD" rate="1.6"/><Cube currency="USD" rate="${usd}"/></Cube></Cube></Envelope>`
+  return `data:application/xml,${encodeURIComponent(body)}`
+}
+
+describe('from', () => {
+  test('applies the default ttl and preserves overrides', () => {
+    const oracle = FxOracle.from({ name: 'test', rates: async () => set })
+    expect(oracle.name).toBe('test')
+    expect(oracle.ttl).toMatchInlineSnapshot(`3600000`)
+    expect(FxOracle.from({ name: 'test', rates: async () => set, ttl: 5 }).ttl).toBe(5)
+  })
+
+  test('resolves the definition rates', async () => {
+    const oracle = FxOracle.from({ name: 'test', rates: async () => set })
+    await expect(oracle.rates()).resolves.toEqual(set)
+  })
+
+  test('rethrows rates failures as RatesError', async () => {
+    const oracle = FxOracle.from({
+      name: 'test',
+      rates: async () => {
+        throw new Error('boom')
+      },
+    })
+    const error = await oracle.rates().catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect(error).toMatchInlineSnapshot(
+      `[FxOracle.RatesError: FX oracle "test" failed to produce rates]`,
+    )
+    expect((error as Error).cause).toMatchInlineSnapshot(`[Error: boom]`)
+  })
+})
+
+describe('ecb', () => {
+  test('fetches and parses the daily reference rates', async () => {
+    const rates = await FxOracle.ecb({ url: feedUrl('1.25') }).rates()
+    expect(rates).toMatchInlineSnapshot(`
+      {
+        "asOf": "2026-01-01T00:00:00.000Z",
+        "base": "EUR",
+        "rates": {
+          "AUD": "1.6",
+          "USD": "1.25",
+        },
+      }
+    `)
+  })
+
+  test.each(['', '-1.25', '1..25'])('rejects malformed rate %j', async (value) => {
+    const error = await FxOracle.ecb({ url: feedUrl(value) })
+      .rates()
+      .catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect((error as Error).cause).toMatchInlineSnapshot(
+      `[FxOracle.ParseError: Rate feed returned an unrecognized payload]`,
+    )
+  })
+
+  test('rejects non-positive rates', async () => {
+    const error = await FxOracle.ecb({ url: feedUrl('0.0') })
+      .rates()
+      .catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect((error as Error).cause).toMatchInlineSnapshot(
+      `[FxOracle.ParseError: Rate feed returned an unrecognized payload]`,
+    )
+  })
+
+  test('rejects rates below fixed-point precision', async () => {
+    const error = await FxOracle.ecb({ url: feedUrl('0.0000000000000000001') })
+      .rates()
+      .catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect((error as Error).cause).toMatchInlineSnapshot(
+      `[FxOracle.ParseError: Rate feed returned an unrecognized payload]`,
+    )
+  })
+
+  test('rejects with RatesError when the feed is unreachable', async () => {
+    const oracle = FxOracle.ecb({ url: 'http://127.0.0.1:1' })
+    const error = await oracle.rates().catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect(error).toMatchInlineSnapshot(
+      `[FxOracle.RatesError: FX oracle "ecb" failed to produce rates]`,
+    )
+  })
+})
+
+describe('rate', () => {
+  test('derives cross rates through the base', () => {
+    expect(FxOracle.rate(set, { from: 'USD', to: 'AUD' })).toMatchInlineSnapshot(
+      `1280000000000000000n`,
+    )
+    expect(FxOracle.rate(set, { from: 'EUR', to: 'USD' })).toMatchInlineSnapshot(
+      `1250000000000000000n`,
+    )
+    expect(FxOracle.rate(set, { from: 'USD', to: 'EUR' })).toMatchInlineSnapshot(
+      `800000000000000000n`,
+    )
+    expect(FxOracle.rate(set, { from: 'USD', to: 'USD' })).toMatchInlineSnapshot(
+      `1000000000000000000n`,
+    )
+  })
+
+  test('returns undefined for currencies the set does not price', () => {
+    expect(FxOracle.rate(set, { from: 'BTC', to: 'USD' })).toBeUndefined()
+    expect(FxOracle.rate(set, { from: 'USD', to: 'XXX' })).toBeUndefined()
+  })
+})