tapimo 0.5.2 → 0.6.0

package/src/internal/FundingQuotes.test.ts

@@ -10,6 +10,7 @@ const baseUsdcRequest = {
 
 describe('listQuotes', () => {
   test('returns normalized successful provider quotes', async () => {
+    const attempts: FundingQuotes.ProviderAttempt[] = []
     let seen: FundingQuotes.QuoteProbeInput | undefined
     const quotes = await FundingQuotes.listQuotes({
       ...baseUsdcRequest,
@@ -33,6 +34,7 @@ describe('listQuotes', () => {
           },
         },
       },
+      onAttempt: (attempt) => attempts.push(attempt),
     })
 
     expect(seen?.candidate.id).toBe('base-usdc-tempo-usdce-relay')
@@ -50,13 +52,23 @@ describe('listQuotes', () => {
         outputAmountFormatted: '0.99',
       },
     })
+    expect(attempts.map(stableAttempt)).toEqual([{ outcome: 'available', provider: 'relay' }])
+    expect(attempts[0]?.durationMs).toEqual(expect.any(Number))
   })
 
   test('returns no static candidates when no adapter is configured', async () => {
-    await expect(FundingQuotes.listQuotes(baseUsdcRequest)).resolves.toEqual([])
+    const attempts: FundingQuotes.ProviderAttempt[] = []
+    await expect(
+      FundingQuotes.listQuotes({
+        ...baseUsdcRequest,
+        onAttempt: (attempt) => attempts.push(attempt),
+      }),
+    ).resolves.toEqual([])
+    expect(attempts).toEqual([])
   })
 
   test('omits provider-declared unavailable quotes', async () => {
+    const attempts: FundingQuotes.ProviderAttempt[] = []
     const quotes = FundingQuotes.listQuotes({
       ...baseUsdcRequest,
       adapters: {
@@ -66,12 +78,15 @@ describe('listQuotes', () => {
           },
         },
       },
+      onAttempt: (attempt) => attempts.push(attempt),
     })
 
     await expect(quotes).resolves.toEqual([])
+    expect(attempts.map(stableAttempt)).toEqual([{ outcome: 'unavailable', provider: 'relay' }])
   })
 
   test('rejects provider failures when no quote succeeds', async () => {
+    const attempts: FundingQuotes.ProviderAttempt[] = []
     const quotes = FundingQuotes.listQuotes({
       ...baseUsdcRequest,
       adapters: {
@@ -81,6 +96,7 @@ describe('listQuotes', () => {
           },
         },
       },
+      onAttempt: (attempt) => attempts.push(attempt),
     })
 
     const cause = await quotes.catch((error: unknown) => error)
@@ -88,6 +104,31 @@ describe('listQuotes', () => {
       failures: [{ cause: expect.any(Error), provider: 'relay' }],
       name: 'FundingQuotes.ProviderQuoteError',
     })
+    expect(attempts.map(stableAttempt)).toEqual([
+      { cause: expect.any(Error), outcome: 'failed', provider: 'relay' },
+    ])
+  })
+
+  test('records thin quotes separately from available quotes', async () => {
+    const attempts: FundingQuotes.ProviderAttempt[] = []
+    const quotes = await FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapters: {
+        relay: {
+          async probeQuote() {
+            return {
+              outputAmount: '990000',
+              sampledAt: '2026-01-01T00:00:00Z',
+              status: 'thin',
+            }
+          },
+        },
+      },
+      onAttempt: (attempt) => attempts.push(attempt),
+    })
+
+    expect(quotes).toHaveLength(1)
+    expect(attempts.map(stableAttempt)).toEqual([{ outcome: 'thin', provider: 'relay' }])
   })
 
   test('rejects successful provider responses without output amounts', async () => {
@@ -108,6 +149,7 @@ describe('listQuotes', () => {
   })
 
   test('aborts providers that exceed the quote deadline', async () => {
+    const attempts: FundingQuotes.ProviderAttempt[] = []
     let aborted = false
     const quotes = FundingQuotes.listQuotes({
       ...baseUsdcRequest,
@@ -122,12 +164,20 @@ describe('listQuotes', () => {
           },
         },
       },
+      onAttempt: (attempt) => attempts.push(attempt),
     })
 
     await expect(quotes).rejects.toThrowErrorMatchingInlineSnapshot(
       `[FundingQuotes.ProviderQuoteError]`,
     )
     expect(aborted).toBe(true)
+    expect(attempts.map(stableAttempt)).toEqual([
+      {
+        cause: expect.any(FundingQuotes.ProviderAdapterTimeoutError),
+        outcome: 'failed',
+        provider: 'relay',
+      },
+    ])
   })
 
   test('passes cache policy through to providers', async () => {
@@ -149,6 +199,7 @@ describe('listQuotes', () => {
   })
 
   test('returns successful quotes when another provider fails', async () => {
+    const attempts: FundingQuotes.ProviderAttempt[] = []
     const quotes = await FundingQuotes.listQuotes({
       ...baseUsdcRequest,
       adapters: {
@@ -167,14 +218,63 @@ describe('listQuotes', () => {
           },
         },
       },
+      onAttempt: (attempt) => attempts.push(attempt),
       provider: undefined,
     })
 
     expect(quotes).toHaveLength(1)
     expect(quotes[0]?.provider.id).toBe('relay')
+    expect(attempts.map(stableAttempt)).toEqual([
+      { cause: expect.any(Error), outcome: 'failed', provider: 'across' },
+      { outcome: 'available', provider: 'relay' },
+    ])
+  })
+
+  test('does not let attempt observers change quote outcomes', async () => {
+    const adapters = {
+      relay: {
+        async probeQuote() {
+          return {
+            outputAmount: '990000',
+            sampledAt: '2026-01-01T00:00:00Z',
+            status: 'available' as const,
+          }
+        },
+      },
+    }
+    await expect(
+      FundingQuotes.listQuotes({
+        ...baseUsdcRequest,
+        adapters,
+        onAttempt() {
+          throw new Error('observer failed')
+        },
+      }),
+    ).resolves.toHaveLength(1)
+
+    await expect(
+      FundingQuotes.listQuotes({
+        ...baseUsdcRequest,
+        adapters: {
+          relay: {
+            async probeQuote() {
+              throw new Error('provider failed')
+            },
+          },
+        },
+        onAttempt() {
+          throw new Error('observer failed')
+        },
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[FundingQuotes.ProviderQuoteError]`)
   })
 })
 
+function stableAttempt(attempt: FundingQuotes.ProviderAttempt) {
+  const { durationMs: _durationMs, ...rest } = attempt
+  return rest
+}
+
 describe('listChains', () => {
   test('returns only chain and token inputs with quote inventory', () => {
     expect(FundingQuotes.listChains().map((chain) => chain.id)).toEqual([
@@ -261,6 +361,41 @@ describe('listQuoteCandidates', () => {
       'ethereum-usdt-tempo-usdt0-squid',
     ])
   })
+
+  test('selects proven Symbiosis stablecoin corridors', () => {
+    const candidates = [
+      FundingQuotes.listQuoteCandidates({
+        destinationToken: 'USDC.e',
+        provider: 'symbiosis',
+        sourceAmount: '1000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'base',
+        sourceToken: 'USDC',
+      })[0],
+      FundingQuotes.listQuoteCandidates({
+        destinationToken: 'USDT0',
+        provider: 'symbiosis',
+        sourceAmount: '1000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'ethereum',
+        sourceToken: 'USDT',
+      })[0],
+      FundingQuotes.listQuoteCandidates({
+        destinationToken: 'USDT0',
+        provider: 'symbiosis',
+        sourceAmount: '1000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'tron',
+        sourceToken: 'USDT',
+      })[0],
+    ]
+
+    expect(candidates.map((candidate) => candidate?.id)).toEqual([
+      'base-usdc-tempo-usdce-symbiosis',
+      'ethereum-usdt-tempo-usdt0-symbiosis',
+      'tron-usdt-tempo-usdt0-symbiosis',
+    ])
+  })
 })
 
 describe('listProviders', () => {
@@ -295,6 +430,13 @@ describe('listProviders', () => {
           "requiresApiKey": true,
           "status": "unconfigured",
         },
+        {
+          "id": "symbiosis",
+          "kind": "crossChainDex",
+          "name": "Symbiosis",
+          "requiresApiKey": false,
+          "status": "unconfigured",
+        },
       ]
     `)
   })

package/src/internal/FundingQuotes.ts

@@ -20,6 +20,7 @@ const sourceChains = [
     providerIds: {
       across: '1',
       relay: '1',
+      symbiosis: '1',
     },
     slug: 'ethereum',
     tokens: [
@@ -75,6 +76,7 @@ const sourceChains = [
       across: '8453',
       relay: '8453',
       rhino: 'BASE',
+      symbiosis: '8453',
     },
     slug: 'base',
     tokens: [
@@ -113,6 +115,7 @@ const sourceChains = [
     providerIds: {
       across: '56',
       relay: '56',
+      symbiosis: '56',
     },
     slug: 'bnb',
     tokens: [
@@ -163,6 +166,7 @@ const sourceChains = [
     name: 'Tron',
     providerIds: {
       rhino: 'TRON',
+      symbiosis: '728126428',
     },
     slug: 'tron',
     tokens: [
@@ -252,6 +256,13 @@ const providers = [
     requiresApiKey: true,
     status: 'unconfigured',
   },
+  {
+    id: 'symbiosis',
+    kind: 'crossChainDex',
+    name: 'Symbiosis',
+    requiresApiKey: false,
+    status: 'unconfigured',
+  },
 ] as const
 
 type TokenInput = (typeof sourceChains)[number]['tokens'][number]
@@ -363,6 +374,27 @@ export type ProviderAdapter = {
 /** Provider adapter registry, keyed by provider id. */
 export type ProviderAdapters = Partial<Record<ProviderId, ProviderAdapter>>
 
+/** One configured provider attempt made while resolving a funding quote request. */
+export type ProviderAttempt =
+  | {
+      /** Wall-clock duration of the provider attempt in milliseconds. */
+      durationMs: number
+      /** Successful or expected-unavailable provider outcome. */
+      outcome: 'available' | 'thin' | 'unavailable'
+      /** Provider that handled the quote candidate. */
+      provider: ProviderId
+    }
+  | {
+      /** Error thrown by the provider boundary. */
+      cause: unknown
+      /** Wall-clock duration of the provider attempt in milliseconds. */
+      durationMs: number
+      /** Failed provider outcome. */
+      outcome: 'failed'
+      /** Provider that handled the quote candidate. */
+      provider: ProviderId
+    }
+
 /** A provider adapter failure retained for bounded request diagnostics. */
 export type ProviderFailure = {
   /** Error thrown by the provider boundary. */
@@ -377,8 +409,10 @@ const inventory: readonly InventoryEntry[] = [
   { destinationToken: 'usdce', provider: 'relay', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC', 'USDT'] }, // prettier-ignore
   { destinationToken: 'usdce', provider: 'rhino', sourceChains: ['base', 'solana'], sourceTokens: ['USDC'] }, // prettier-ignore
   { destinationToken: 'usdce', provider: 'squid', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'symbiosis', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
   { destinationToken: 'usdt0', provider: 'rhino', sourceChains: ['tron'], sourceTokens: ['USDT'] }, // prettier-ignore
   { destinationToken: 'usdt0', provider: 'squid', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDT'] }, // prettier-ignore
+  { destinationToken: 'usdt0', provider: 'symbiosis', sourceChains: ['ethereum', 'base', 'bnb', 'tron'], sourceTokens: ['USDT'] }, // prettier-ignore
 ]
 
 type InventoryEntry = {
@@ -428,30 +462,61 @@ export declare namespace listProviders {
 
 /** Returns successful live funding quotes from configured providers. */
 export async function listQuotes(options: listQuotes.Options) {
-  const candidates = listQuoteCandidates(options)
+  const adapters = options.adapters ?? {}
+  const candidates = listQuoteCandidates(options).flatMap((candidate) => {
+    const adapter = adapters[candidate.provider.id as ProviderId]
+    return adapter ? [{ adapter, candidate }] : []
+  })
+  const attempts = new Map<number, ProviderAttempt>()
   const results = await Promise.allSettled(
-    candidates.map((candidate) =>
-      quoteCandidate(candidate, {
-        adapters: options.adapters ?? {},
-        cache: options.cache ?? { bypass: false },
-        request: {
-          destinationToken: options.destinationToken,
-          provider: options.provider,
-          sourceAmount: options.sourceAmount,
-          sourceAmountUnits: options.sourceAmountUnits,
-          sourceChain: options.sourceChain,
-          sourceToken: options.sourceToken,
-        },
-        timeoutMs: options.adapterTimeoutMs ?? defaultAdapterTimeoutMs,
-      }),
-    ),
+    candidates.map(async ({ adapter, candidate }, index) => {
+      const start = performance.now()
+      try {
+        const result = await quoteCandidate(candidate, {
+          adapter,
+          cache: options.cache ?? { bypass: false },
+          request: {
+            destinationToken: options.destinationToken,
+            provider: options.provider,
+            sourceAmount: options.sourceAmount,
+            sourceAmountUnits: options.sourceAmountUnits,
+            sourceChain: options.sourceChain,
+            sourceToken: options.sourceToken,
+          },
+          timeoutMs: options.adapterTimeoutMs ?? defaultAdapterTimeoutMs,
+        })
+        attempts.set(index, {
+          durationMs: performance.now() - start,
+          outcome: result.outcome,
+          provider: candidate.provider.id,
+        })
+        return 'quote' in result ? result.quote : undefined
+      } catch (cause) {
+        attempts.set(index, {
+          cause,
+          durationMs: performance.now() - start,
+          outcome: 'failed',
+          provider: candidate.provider.id,
+        })
+        throw cause
+      }
+    }),
   )
+  for (const index of candidates.keys()) {
+    const attempt = attempts.get(index)
+    if (!attempt) continue
+    try {
+      options.onAttempt?.(attempt)
+    } catch {
+      // Observability hooks never alter funding quote behavior.
+    }
+  }
   const quotes = results.flatMap((result) =>
     result.status === 'fulfilled' && result.value ? [result.value] : [],
   )
   const failures = results.flatMap((result, index) =>
     result.status === 'rejected'
-      ? [{ cause: result.reason, provider: candidates[index]!.provider.id }]
+      ? [{ cause: result.reason, provider: candidates[index]!.candidate.provider.id }]
       : [],
   )
   if (quotes.length === 0 && failures.length > 0) throw new ProviderQuoteError(failures)
@@ -519,6 +584,8 @@ export declare namespace listQuotes {
     adapterTimeoutMs?: number | undefined
     /** Cache policy for provider-side discovery and quote lookups. */
     cache?: CachePolicy | undefined
+    /** Receives one bounded observation for every configured provider attempt. */
+    onAttempt?: ((attempt: ProviderAttempt) => void) | undefined
   }
 }
 
@@ -544,18 +611,15 @@ function decimalFromBaseUnits(baseUnits: string, decimals: number) {
 async function quoteCandidate(
   candidate: QuoteCandidate,
   options: {
-    adapters: ProviderAdapters
+    adapter: ProviderAdapter
     cache: CachePolicy
     request: QuoteRequest
     timeoutMs: number
   },
 ) {
-  const adapter = options.adapters[candidate.provider.id as ProviderId]
-  if (!adapter) return undefined
-
   const quote = await runWithTimeout(
     (signal) =>
-      adapter.probeQuote(
+      options.adapter.probeQuote(
         {
           cache: options.cache,
           destinationChain: candidate.destinationChain,
@@ -570,18 +634,21 @@ async function quoteCandidate(
       ),
     options.timeoutMs,
   )
-  if (quote.status === 'unavailable') return undefined
+  if (quote.status === 'unavailable') return { outcome: quote.status }
   if (
     (quote.status !== 'available' && quote.status !== 'thin') ||
     quote.outputAmount === undefined ||
     quote.outputAmount === null
   )
     throw new InvalidProviderQuoteError()
-  return formatFundingQuote(candidate, {
-    ...quote,
-    outputAmount: quote.outputAmount,
-    status: quote.status,
-  })
+  return {
+    outcome: quote.status,
+    quote: formatFundingQuote(candidate, {
+      ...quote,
+      outputAmount: quote.outputAmount,
+      status: quote.status,
+    }),
+  }
 }
 
 function formatChain(chain: SourceChainInput) {

package/src/internal/Log.test-d.ts

@@ -0,0 +1,21 @@
+import type * as FundingQuotes from './FundingQuotes.js'
+import type * as Log from './Log.js'
+
+test('bounds funding provider metric identifiers', () => {
+  const provider = null as never as FundingQuotes.ProviderId
+  const id: Log.FundingProviderAttempt['id'] = provider
+  const provider_roundTrip: FundingQuotes.ProviderId = id
+  void provider_roundTrip
+
+  const attempt = {
+    durationMs: 1,
+    id: 'relay',
+    operation: 'quote/v2',
+    outcome: 'available',
+  } satisfies Log.FundingProviderAttempt
+  void attempt
+
+  // @ts-expect-error arbitrary provider names would create unbounded metric tags
+  const invalid: Log.FundingProviderAttempt['id'] = 'user-controlled-provider'
+  void invalid
+})

package/src/internal/Log.test.ts

@@ -177,6 +177,56 @@ describe('middleware', () => {
     `)
   })
 
+  test('includes bounded funding provider attempts', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.get('/funding', (c) => {
+      c.set('fundingProviderAttempts', [
+        {
+          durationMs: 12.5,
+          id: 'relay',
+          operation: 'quote/v2',
+          outcome: 'available',
+        },
+        {
+          durationMs: 25,
+          failure: 'timeout',
+          id: 'across',
+          operation: 'swap/approval',
+          outcome: 'failed',
+        },
+      ])
+      return c.json({ ok: true }, 200)
+    })
+
+    await api.request('/funding')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "fundingProviderAttempts": [
+          {
+            "durationMs": 12.5,
+            "id": "relay",
+            "operation": "quote/v2",
+            "outcome": "available",
+          },
+          {
+            "durationMs": 25,
+            "failure": "timeout",
+            "id": "across",
+            "operation": "swap/approval",
+            "outcome": "failed",
+          },
+        ],
+        "level": "info",
+        "method": "GET",
+        "path": "/funding",
+        "route": "/funding",
+        "status": 200,
+      }
+    `)
+  })
+
   test('logs thrown errors at error level', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })

package/src/internal/Log.ts

@@ -4,12 +4,15 @@ import type { RequestIdVariables } from 'hono/request-id'
 import * as ApiKey from '../ApiKey.js'
 import type * as Auth from './Auth.js'
 import type * as EdgeCache from './EdgeCache.js'
+import type * as FundingQuotes from './FundingQuotes.js'
 import type * as Timing from './Timing.js'
 
 /** Hono variables read by the request logger and written by other layers. */
 export type Variables = {
   /** Stable error code recorded by `Response.error` for the request log entry. */
   errorCode?: string | undefined
+  /** Bounded outcomes for funding providers attempted by the request. */
+  fundingProviderAttempts?: Entry['fundingProviderAttempts'] | undefined
   /** Redacted provider failure details recorded by an upstream adapter. */
   providerFailure?: Entry['provider'] | undefined
   /** Redacted provider failures when multiple upstream adapters fail. */
@@ -35,7 +38,7 @@ export type 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: string
   /** Provider operation identifier. */
@@ -44,6 +47,20 @@ export type ProviderFailure = {
   status?: number | undefined
 }
 
+/** Bounded operational result for one funding quote provider attempt. */
+export type FundingProviderAttempt = {
+  /** Wall-clock duration of the provider attempt in milliseconds. */
+  durationMs: number
+  /** Failure class, present only when the provider attempt failed. */
+  failure?: ProviderFailure['failure'] | undefined
+  /** Provider identifier. */
+  id: FundingQuotes.ProviderId
+  /** Stable upstream operation identifier. */
+  operation: string
+  /** Provider attempt outcome. */
+  outcome: 'available' | 'failed' | 'thin' | 'unavailable'
+}
+
 /** One canonical request log entry. */
 export type Entry = {
   /** `'hit'` when the edge response cache served the request without reaching the origin handlers. */
@@ -52,6 +69,8 @@ export type Entry = {
   duration: number
   /** Stable error code when the response is a JSON error envelope (e.g. `not_found`, `api_key_invalid`). */
   errorCode?: string | undefined
+  /** Bounded funding provider attempts made while serving the request. */
+  fundingProviderAttempts?: readonly FundingProviderAttempt[] | undefined
   /** Log level derived from the response status: 5xx `error`, 4xx `warn`, else `info`. */
   level: Level
   /** Request method. */
@@ -140,6 +159,9 @@ export function middleware<environment extends Environment = Environment>(
     // (the same pattern EdgeCache uses for its cross-layer reads).
     const principal = c.get('principal' as never) as Auth.Principal | undefined
     const errorCode = c.get('errorCode' as never) as string | undefined
+    const fundingProviderAttempts = c.get('fundingProviderAttempts' as never) as
+      | Entry['fundingProviderAttempts']
+      | undefined
     const provider = c.get('providerFailure' as never) as Entry['provider']
     const providerFailures = c.get('providerFailures' as never) as Entry['providerFailures']
 
@@ -170,6 +192,7 @@ export function middleware<environment extends Environment = Environment>(
       ...(c.get('edgeCacheStatus' as never) === 'hit' ? { cache: 'hit' as const } : {}),
       duration: round(duration),
       ...(errorCode === undefined ? {} : { errorCode }),
+      ...(fundingProviderAttempts === undefined ? {} : { fundingProviderAttempts }),
       level: status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info',
       method: c.req.method,
       path: url.pathname,