tapimo 0.2.0 → 0.4.0

package/src/apps/data/App.ts

@@ -17,6 +17,7 @@ import { blocks, blocksByTimestampCompat } from './routes/blocks.js'
 import { coingecko } from './routes/coingecko.js'
 import { exchanges } from './routes/exchanges.js'
 import { feeAmm } from './routes/fee-amm.js'
+import { funding } from './routes/funding.js'
 import { indexer } from './routes/indexer.js'
 import { receipts } from './routes/receipts.js'
 import { rpc } from './routes/rpc.js'
@@ -94,6 +95,34 @@ export function data(options: data.Options = {}) {
       if (!parsed.success || supportedChainIds.has(parsed.data)) return next()
       return Response.unsupportedChainId(c, parsed.data, supportedChainIds)
     })
+    // Sandbox keys are testnet-only. A chain-scoped data route defaults to
+    // mainnet, so a sandbox key that omits `chainId` (or targets mainnet) is
+    // refused with a clear message telling the caller to pass a testnet
+    // `chainId`. The relay resolves its chain from the request body, not the
+    // query, so it is skipped and enforces the rule in its sponsor validation.
+    .use('*', async (c, next) => {
+      const relay = Path.join(c.get('basePath') ?? '', 'rpc/relay')
+      if (c.req.path === relay || c.req.path.startsWith(`${relay}/`)) return next()
+
+      const principal = Auth.getPrincipal(c)
+      if (principal?.type !== 'api_key' || principal.environment !== 'sandbox') return next()
+
+      const raw = c.req.query('chainId') ?? c.req.query('chain_id')
+      // Absent falls back to the group default (mainnet); a malformed value
+      // stays with the route's own validator rather than the sandbox message.
+      const chainId = (() => {
+        if (raw === undefined) return defaultChainId
+        const parsed = Schema.ChainId.safeParse(raw)
+        return parsed.success ? parsed.data : undefined
+      })()
+      if (chainId === undefined || !Viem.isMainnet(chainId)) return next()
+
+      return Response.error(c, {
+        code: 'api_key_forbidden',
+        message: 'Sandbox API keys only support testnet. Pass a testnet `chainId`.',
+        status: 403,
+      })
+    })
     // Serve static API assets (e.g. verified-token icons) from the configured
     // store; a no-op fall-through when no store is configured (logo URIs simply
     // go unresolved).
@@ -111,6 +140,7 @@ export function data(options: data.Options = {}) {
     .route('/', blocks())
     .route('/', exchanges())
     .route('/', feeAmm())
+    .route('/', funding(options.fundingRoutes))
     .route('/', indexer())
     .route('/', receipts())
     .route('/', tokenlist())
@@ -133,6 +163,8 @@ export declare namespace data {
     assets?: Assets.Assets | undefined
     /** Default Tempo chain id for requests that omit `chainId`. */
     defaultChainId?: Viem.ChainId | undefined
+    /** Funding route provider adapter configuration. Omit to serve static inventory only. */
+    fundingRoutes?: funding.Options | undefined
     /** Tempo RPC options: a static config, or a per-request resolver that routes by request principal to a separate (e.g. public, no-auth) RPC. */
     rpc?: Viem.getClient.Rpc | undefined
     /** Extra chain ids this deployment serves, beyond the built-in public chains and `defaultChainId`. A `chainId` outside this set is rejected with a 400. */
@@ -178,6 +210,8 @@ const openapi = {
     { name: 'Blocks', description: 'The ordered batches of transactions making up the chain.' },
     { name: 'Exchange', description: "Tempo's built-in stablecoin exchange: pairs, swaps, orders, prices." }, // prettier-ignore
     { name: 'Fee AMM', description: 'Pools that convert stablecoins to pay fees.' },
+    { name: 'Funding', description: 'Routes and inventory for moving stablecoins into Tempo.' },
+    { name: 'Providers', description: 'Provider metadata, capabilities, and integration status.' },
     { name: 'Tokens', description: 'TIP-20 token details, supply, and holders.' },
     { name: 'Transactions', description: 'Transactions submitted to Tempo, and their receipts.' },
     { name: 'Transfers', description: 'Token movements from executing transactions.' },
@@ -196,6 +230,8 @@ const openapi = {
         'Blocks',
         'Exchange',
         'Fee AMM',
+        'Funding',
+        'Providers',
         'Tokens',
         'Transactions',
         'Transfers',
@@ -203,6 +239,7 @@ const openapi = {
         'Webhooks',
         'Indexer',
         'RPC',
+        'MCP',
         'CoinGecko',
       ],
     },

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

@@ -0,0 +1,281 @@
+import * as FundingRoutes from '../../internal/FundingRoutes.js'
+import * as FundingRouteProviders from './FundingRouteProviders.js'
+
+const now = () => new Date('2026-01-01T00:00:00.000Z')
+
+describe('FundingRouteProviders', () => {
+  test('maps Across suggested-fees responses into quote probes', async () => {
+    const requests: RecordedRequest[] = []
+    const fetch = recordingFetch(requests, async () =>
+      jsonResponse({
+        estimatedFillTimeSec: 2,
+        limits: {
+          maxDeposit: '2000000',
+          maxDepositInstant: '1500000',
+          minDeposit: '500000',
+        },
+        outputAmount: '990000',
+        relayFeePct: '1200000000000000',
+        timestamp: '1767225600',
+      }),
+    )
+    const adapter = FundingRouteProviders.across({
+      apiKey: 'across-api-key',
+      baseUrl: 'https://across.test/api/',
+      fetch,
+      integratorId: 'tempo',
+      now,
+    })
+
+    const result = await adapter.probeQuote(
+      await probeInput('across'),
+      new AbortController().signal,
+    )
+
+    expect(requests).toHaveLength(1)
+    expect(requests[0]?.url.pathname).toBe('/api/suggested-fees')
+    expect(requests[0]?.url.searchParams.get('originChainId')).toBe('8453')
+    expect(requests[0]?.url.searchParams.get('destinationChainId')).toBe('4217')
+    expect(requests[0]?.url.searchParams.get('amount')).toBe('1000000')
+    expect(requests[0]?.url.searchParams.get('integratorId')).toBe('tempo')
+    expect(requests[0]?.url.searchParams.get('allowUnmatchedDecimals')).toBe('true')
+    expect(new Headers(requests[0]?.init?.headers).get('authorization')).toBe(
+      'Bearer across-api-key',
+    )
+    expect(result).toMatchObject({
+      expiresAt: '2026-01-01T00:10:00.000Z',
+      limits: {
+        instantSourceAmount: '1500000',
+        maxSourceAmount: '2000000',
+        minSourceAmount: '500000',
+      },
+      outputAmount: '990000',
+      outputAmountFormatted: '0.99',
+      quality: {
+        availableVolumeUsd: '2',
+        estimatedSeconds: 2,
+        feeBps: 12,
+        instantVolumeUsd: '1.5',
+        liquiditySource: 'providerLimit',
+        sourceDetail: 'across:suggested-fees',
+        tier: 'liquid',
+      },
+      sampledAt: '2026-01-01T00:00:00.000Z',
+      status: 'available',
+    })
+  })
+
+  test('maps recognized Across quote errors to unavailable probes', async () => {
+    const fetch = recordingFetch([], async () =>
+      jsonResponse({ code: 'AMOUNT_TOO_HIGH', message: 'Amount exceeds max deposit' }, 400),
+    )
+    const adapter = FundingRouteProviders.across({
+      apiKey: 'across-api-key',
+      fetch,
+      integratorId: 'tempo',
+      now,
+    })
+
+    const result = await adapter.probeQuote(
+      await probeInput('across'),
+      new AbortController().signal,
+    )
+
+    expect(result).toMatchObject({
+      quality: {
+        liquiditySource: 'providerLimit',
+        score: 0,
+        sourceDetail: 'across:suggested-fees:AMOUNT_TOO_HIGH',
+        tier: 'unavailable',
+      },
+      sampledAt: '2026-01-01T00:00:00.000Z',
+      status: 'unavailable',
+    })
+  })
+
+  test('maps Relay liquidity and quote responses into quote probes', async () => {
+    const requests: RecordedRequest[] = []
+    const route = await staticRoute('relay')
+    const fetch = recordingFetch(requests, async (request) => {
+      if (request.url.pathname === '/quote/v2')
+        return jsonResponse({
+          details: {
+            currencyOut: {
+              amount: '990000',
+              minimumAmount: '980000',
+            },
+            timeEstimate: 15,
+            totalImpact: { percent: '-1.20' },
+          },
+        })
+      return jsonResponse({
+        liquidity: [
+          {
+            address: route.destinationToken.address.toUpperCase(),
+            amountUsd: '5.00',
+            balance: '5000000',
+            chainId: 4217,
+          },
+        ],
+      })
+    })
+    const adapter = FundingRouteProviders.relay({
+      apiKey: 'relay-api-key',
+      fetch,
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    const result = await adapter.probeQuote(
+      probeInputFromRoute(route),
+      new AbortController().signal,
+    )
+
+    expect(requests.map((request) => request.url.pathname)).toEqual([
+      '/quote/v2',
+      '/chains/liquidity',
+    ])
+    expect(requests[1]?.url.searchParams.get('chainId')).toBe('4217')
+    expect(new Headers(requests[0]?.init?.headers).get('x-api-key')).toBe('relay-api-key')
+    expect(jsonRequestBody(requests[0])).toMatchObject({
+      amount: '1000000',
+      destinationChainId: 4217,
+      destinationCurrency: route.destinationToken.address,
+      originChainId: 8453,
+      originCurrency: route.sourceToken.address,
+      tradeType: 'EXACT_INPUT',
+      user: '0x1111111111111111111111111111111111111111',
+    })
+    expect(result).toMatchObject({
+      limits: null,
+      minimumOutputAmount: '980000',
+      outputAmount: '990000',
+      outputAmountFormatted: '0.99',
+      quality: {
+        availableVolumeUsd: '5.00',
+        estimatedSeconds: 15,
+        feeBps: null,
+        instantVolumeUsd: '5.00',
+        liquiditySource: 'providerQuote',
+        sourceDetail: 'relay:quote-v2',
+        tier: 'liquid',
+      },
+      sampledAt: '2026-01-01T00:00:00.000Z',
+      status: 'available',
+    })
+  })
+
+  test('keeps Relay quotes when the liquidity probe fails', async () => {
+    const route = await staticRoute('relay')
+    const fetch = recordingFetch([], async (request) => {
+      if (request.url.pathname === '/quote/v2')
+        return jsonResponse({
+          details: {
+            currencyOut: {
+              amount: '990000',
+              minimumAmount: '980000',
+            },
+            timeEstimate: 15,
+          },
+        })
+      return jsonResponse({ message: 'temporarily unavailable' }, 503)
+    })
+    const adapter = FundingRouteProviders.relay({
+      fetch,
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    const result = await adapter.probeQuote(
+      probeInputFromRoute(route),
+      new AbortController().signal,
+    )
+
+    expect(result).toMatchObject({
+      outputAmount: '990000',
+      quality: {
+        availableVolumeUsd: null,
+        instantVolumeUsd: null,
+        liquiditySource: 'providerQuote',
+        tier: 'unknown',
+      },
+      status: 'unknown',
+    })
+  })
+})
+
+type RecordedRequest = {
+  init: RequestInit | undefined
+  url: URL
+}
+
+async function staticRoute(
+  provider: FundingRoutes.ProviderId,
+): Promise<FundingRoutes.QuoteProbeInput['route']> {
+  const [route] = await FundingRoutes.listRoutes({
+    limit: 10,
+    provider,
+    sourceAmount: '1000000',
+    sourceAmountUnits: 'baseUnits',
+    sourceToken: 'USDC',
+    sourceChain: 'base',
+  })
+  if (!route) throw new Error(`Missing ${provider} route`)
+  return route as FundingRoutes.QuoteProbeInput['route']
+}
+
+async function probeInput(provider: FundingRoutes.ProviderId) {
+  return probeInputFromRoute(await staticRoute(provider))
+}
+
+function probeInputFromRoute(
+  route: FundingRoutes.QuoteProbeInput['route'],
+): FundingRoutes.QuoteProbeInput {
+  return {
+    cache: { bypass: false },
+    destinationChain: route.destinationChain,
+    destinationToken: route.destinationToken,
+    include: ['quotes'],
+    request: {
+      include: ['quotes'],
+      limit: 10,
+      provider: route.provider.id,
+      sourceAmount: route.sourceAmount.amount,
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: route.sourceChain.id,
+      sourceToken: route.sourceToken.symbol,
+    },
+    route,
+    sourceAmount: route.sourceAmount,
+    sourceChain: route.sourceChain,
+    sourceToken: route.sourceToken,
+  }
+}
+
+function recordingFetch(
+  requests: RecordedRequest[],
+  respond: (request: RecordedRequest) => Response | Promise<Response>,
+): typeof globalThis.fetch {
+  return async (input, init) => {
+    const request = { init, url: toUrl(input) }
+    requests.push(request)
+    return respond(request)
+  }
+}
+
+function toUrl(input: Parameters<typeof globalThis.fetch>[0]) {
+  if (input instanceof Request) return new URL(input.url)
+  return new URL(String(input))
+}
+
+function jsonResponse(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    headers: { 'content-type': 'application/json' },
+    status,
+  })
+}
+
+function jsonRequestBody(request: RecordedRequest | undefined) {
+  if (typeof request?.init?.body !== 'string') throw new Error('Expected JSON request body')
+  return JSON.parse(request.init.body) as unknown
+}