tapimo 0.2.0 → 0.4.0

package/src/internal/Fees.ts

@@ -0,0 +1,51 @@
+import { Hex } from 'ox'
+
+// Tempo gas prices (`maxFeePerGas`, `effectiveGasPrice`, block base fee) are
+// denominated in attodollars (10^-18 USD) per gas, while fee-token balances
+// use 6 decimals (microdollars, 10^-6 USD). The charged fee is
+// `ceil(gas × gasPrice / 10^12)`, mirroring `calc_gas_balance_spending` in
+// tempoxyz/tempo.
+
+/** Attodollar exponent gas prices use (10^-18 USD per gas), fixed by the fee spec. */
+const attoDecimals = 18
+
+/** Fee-token decimals: TIP-20 fixes 6 (1 token unit = 1 microdollar). */
+export const tokenDecimals = 6
+
+/** Scaling between attodollar gas math and fee-token units, derived from the exponents. */
+export const scalingFactor = 10n ** BigInt(attoDecimals - tokenDecimals)
+
+/**
+ * Fee in fee-token base units for a gas amount priced in attodollars per gas
+ * (ceiling division). Works for actual fees (`gasUsed × effectiveGasPrice`)
+ * and signed caps (`gas × maxFeePerGas`) alike.
+ *
+ * @param gas - Gas amount.
+ * @param gasPrice - Price in attodollars per gas.
+ * @returns The fee in fee-token base units.
+ */
+export function fromGas(gas: bigint, gasPrice: bigint): bigint {
+  return (gas * gasPrice + scalingFactor - 1n) / scalingFactor
+}
+
+/**
+ * Signed fee cap of a candidate transaction in fee-token base units:
+ * `gas × maxFeePerGas` (attodollars) scaled through {@link fromGas}. Undefined
+ * when either field is missing or unparseable, so callers can fail closed.
+ *
+ * @param request - Transaction-shaped fee fields.
+ * @returns The cap in base units, or undefined.
+ */
+export function maxOf(request: { gas?: unknown; maxFeePerGas?: unknown }): bigint | undefined {
+  const gas = toBigInt(request.gas)
+  const maxFeePerGas = toBigInt(request.maxFeePerGas)
+  if (gas === undefined || maxFeePerGas === undefined) return undefined
+  return fromGas(gas, maxFeePerGas)
+}
+
+/** Fee fields arrive as bigints (raw envelopes) or hex quantities (fills). */
+function toBigInt(value: unknown): bigint | undefined {
+  if (typeof value === 'bigint') return value
+  if (typeof value === 'string' && Hex.validate(value)) return Hex.toBigInt(value)
+  return undefined
+}

package/src/internal/FundingRoutes.test.ts

@@ -0,0 +1,213 @@
+import * as FundingRoutes from './FundingRoutes.js'
+
+const baseUsdcRequest = {
+  limit: 10,
+  provider: 'across',
+  sourceAmount: '1000000',
+  sourceAmountUnits: 'baseUnits',
+  sourceChain: 'base',
+  sourceToken: 'USDC',
+} as const
+
+describe('listRoutes', () => {
+  test('enriches static candidates with adapter quote probes', async () => {
+    let seen: FundingRoutes.QuoteProbeInput | undefined
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapters: {
+        across: {
+          async probeQuote(input, signal) {
+            seen = input
+            expect(signal.aborted).toBe(false)
+            expect(input.cache.bypass).toBe(false)
+            expect(input.destinationChain.id).toBe('eip155:4217')
+            expect(input.destinationToken.symbol).toBe('USDC.e')
+            expect(input.include).toEqual([])
+            expect(input.request.sourceChain).toBe('base')
+            return {
+              expiresAt: '2026-01-01T00:00:30Z',
+              limits: {
+                instantSourceAmount: '1000000000',
+                maxSourceAmount: '100000000000',
+                minSourceAmount: '500000',
+              },
+              minimumOutputAmount: '980000',
+              outputAmount: '990000',
+              outputAmountFormatted: '0.99',
+              quality: {
+                availableVolumeUsd: '1000.00',
+                estimatedSeconds: 4,
+                feeBps: 12,
+                historicalVolumeUsd24h: '100000.00',
+                instantVolumeUsd: '1000.00',
+                liquiditySource: 'providerQuote',
+                score: 91,
+                sourceDetail: 'providerEndpoint',
+                tier: 'liquid',
+              },
+              sampledAt: '2026-01-01T00:00:00Z',
+              status: 'available',
+            }
+          },
+        },
+      },
+    })
+
+    expect(seen?.route.id).toBe('base-usdc-tempo-usdce-across')
+    expect(seen?.sourceAmount.amount).toBe('1000000')
+    expect(seen?.sourceChain.id).toBe('eip155:8453')
+    expect(seen?.sourceToken.symbol).toBe('USDC')
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({
+      errorCode: null,
+      id: 'base-usdc-tempo-usdce-across',
+      quality: {
+        availableVolumeUsd: '1000.00',
+        estimatedSeconds: 4,
+        feeBps: 12,
+        historicalVolumeUsd24h: '100000.00',
+        instantVolumeUsd: '1000.00',
+        liquiditySource: 'providerQuote',
+        score: 91,
+        sourceDetail: 'providerEndpoint',
+        tier: 'liquid',
+      },
+      quote: {
+        expiresAt: '2026-01-01T00:00:30Z',
+        inputAmount: '1000000',
+        limits: {
+          instantSourceAmount: '1000000000',
+          maxSourceAmount: '100000000000',
+          minSourceAmount: '500000',
+        },
+        minimumOutputAmount: '980000',
+        outputAmount: '990000',
+        outputAmountFormatted: '0.99',
+        sampledAt: '2026-01-01T00:00:00Z',
+      },
+      status: 'available',
+    })
+  })
+
+  test('leaves candidates static when their provider has no adapter', async () => {
+    let calls = 0
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapters: {
+        relay: {
+          async probeQuote() {
+            calls += 1
+            throw new Error('unexpected call')
+          },
+        },
+      },
+    })
+
+    expect(calls).toBe(0)
+    expect(routes[0]).toMatchObject({
+      quality: {
+        liquiditySource: 'staticInventory',
+        sourceDetail: null,
+        tier: 'unknown',
+      },
+      quote: null,
+      status: 'unknown',
+    })
+  })
+
+  test('marks candidates as errors when an adapter throws', async () => {
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapters: {
+        across: {
+          async probeQuote() {
+            throw new Error('upstream unavailable')
+          },
+        },
+      },
+    })
+
+    expect(routes[0]).toMatchObject({
+      errorCode: 'provider_error',
+      quality: {
+        liquiditySource: 'providerError',
+        sourceDetail: null,
+        tier: 'error',
+      },
+      quote: null,
+      status: 'error',
+    })
+  })
+
+  test('aborts slow adapters and marks candidates as timed-out errors', async () => {
+    let aborted = false
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapterTimeoutMs: 1,
+      adapters: {
+        across: {
+          probeQuote(_input, signal) {
+            signal.addEventListener('abort', () => {
+              aborted = true
+            })
+            return new Promise<FundingRoutes.QuoteProbeResult>(() => {})
+          },
+        },
+      },
+    })
+
+    expect(aborted).toBe(true)
+    expect(routes[0]).toMatchObject({
+      errorCode: 'provider_timeout',
+      quality: {
+        liquiditySource: 'providerError',
+        sourceDetail: null,
+        tier: 'error',
+      },
+      quote: null,
+      status: 'error',
+    })
+  })
+
+  test('passes include and cache policy through to adapters', async () => {
+    let seen: FundingRoutes.QuoteProbeInput | undefined
+    const routes = await FundingRoutes.listRoutes({
+      ...baseUsdcRequest,
+      adapters: {
+        across: {
+          async probeQuote(input) {
+            seen = input
+            return {
+              errorCode: 'provider_unavailable',
+              sampledAt: '2026-01-01T00:00:00Z',
+              status: 'error',
+            }
+          },
+        },
+      },
+      cache: { bypass: true },
+      include: ['quotes'],
+    })
+
+    expect(seen?.cache.bypass).toBe(true)
+    expect(seen?.include).toEqual(['quotes'])
+    expect(seen?.request.include).toEqual(['quotes'])
+    expect(routes[0]).toMatchObject({
+      errorCode: 'provider_unavailable',
+      quote: null,
+      status: 'error',
+    })
+  })
+})
+
+describe('parseInclude', () => {
+  test('parses comma-separated include values', () => {
+    expect(FundingRoutes.parseInclude('quotes,quotes')).toEqual(['quotes'])
+  })
+
+  test('rejects unsupported include values', () => {
+    expect(() => FundingRoutes.parseInclude('quotes,debug')).toThrow(
+      FundingRoutes.UnsupportedIncludeError,
+    )
+  })
+})