tapimo 0.11.0 → 0.12.0

package/src/internal/funding/providers/index.test.ts

@@ -4,6 +4,7 @@ import * as Across from './across.js'
 import * as Relay from './relay.js'
 import * as Rhino from './rhino.js'
 import * as Squid from './squid.js'
+import * as Stargate from './stargate.js'
 import * as Symbiosis from './symbiosis.js'
 
 const now = () => new Date('2026-01-01T00:00:00.000Z')
@@ -21,6 +22,10 @@ const providers = [
     integratorId: 'squid-integrator-id',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
+  Stargate.stargate({
+    apiKey: 'layerzero-api-key',
+    userAddress: '0x1111111111111111111111111111111111111111',
+  }),
   Symbiosis.symbiosis({ userAddress: '0x1111111111111111111111111111111111111111' }),
 ] as const
 
@@ -335,6 +340,126 @@ describe('funding providers', () => {
     })
   })
 
+  test('maps the best Stargate quote to an available quote result', async () => {
+    const requests: RecordedRequest[] = []
+    const candidate = quoteCandidate('stargate')
+    const fetch = recordingFetch(requests, async () => jsonResponse(stargateQuotes(candidate)))
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      baseUrl: 'https://layerzero.test/v1/',
+      fetch,
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    const result = await provider.getQuote(getQuoteInput(candidate), new AbortController().signal)
+
+    expect(requests).toHaveLength(1)
+    expect(requests[0]?.url.pathname).toBe('/v1/quotes')
+    expect(new Headers(requests[0]?.init?.headers).get('user-agent')).toBe('tempo-api')
+    expect(new Headers(requests[0]?.init?.headers).get('x-api-key')).toBe('layerzero-api-key')
+    expect(jsonRequestBody(requests[0])).toEqual({
+      amount: '1000000',
+      dstChainKey: 'tempo',
+      dstTokenAddress: candidate.destinationToken.address,
+      dstWalletAddress: '0x1111111111111111111111111111111111111111',
+      options: { amountType: 'EXACT_SRC_AMOUNT' },
+      srcChainKey: 'base',
+      srcTokenAddress: candidate.sourceToken.address,
+      srcWalletAddress: '0x1111111111111111111111111111111111111111',
+    })
+    expect(result).toEqual({
+      expiresAt: '2026-01-01T00:01:00.000Z',
+      destinationAmountMin: '999100',
+      destinationAmount: '999600',
+      quality: {
+        estimatedSeconds: 259,
+        liquiditySource: 'providerQuote',
+        sourceDetail: 'stargate:value-transfer-v1:bus',
+        tier: 'liquid',
+      },
+      sampledAt: '2026-01-01T00:00:00.000Z',
+      status: 'available',
+    })
+  })
+
+  test('skips expired Stargate alternatives', async () => {
+    const candidate = quoteCandidate('stargate')
+    const response = stargateQuotes(candidate)
+    response.quotes[2]!.expiresAt = '2026-01-01T00:00:00.000Z'
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      fetch: recordingFetch([], async () => jsonResponse(response)),
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    await expect(
+      provider.getQuote(getQuoteInput(candidate), new AbortController().signal),
+    ).resolves.toMatchObject({
+      destinationAmountMin: '999000',
+      destinationAmount: '999500',
+      quality: {
+        sourceDetail: 'stargate:value-transfer-v1:taxi',
+        tier: 'liquid',
+      },
+      status: 'available',
+    })
+  })
+
+  test('exposes Base and Ethereum Stargate quote candidates', () => {
+    expect(
+      ['base', 'ethereum'].map((sourceChain) => quoteCandidate('stargate', { sourceChain }).id),
+    ).toEqual(['base-usdc-tempo-usdce-stargate', 'ethereum-usdc-tempo-usdce-stargate'])
+  })
+
+  test('maps responses without Stargate routes to unavailable quote results', async () => {
+    const candidate = quoteCandidate('stargate')
+    const response = stargateQuotes(candidate)
+    response.quotes = response.quotes.filter((quote) => quote.routeSteps[0]?.type === 'CCTP')
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      fetch: recordingFetch([], async () => jsonResponse(response)),
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    await expect(
+      provider.getQuote(getQuoteInput(candidate), new AbortController().signal),
+    ).resolves.toMatchObject({
+      quality: {
+        sourceDetail: 'stargate:value-transfer-v1:NO_STARGATE_ROUTE',
+        tier: 'unavailable',
+      },
+      status: 'unavailable',
+    })
+  })
+
+  test('rejects malformed Stargate quotes', async () => {
+    const candidate = quoteCandidate('stargate')
+    const response = stargateQuotes(candidate)
+    response.quotes[2]!.srcAmount = '1'
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      fetch: recordingFetch([], async () => jsonResponse(response)),
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+
+    await expect(
+      provider.getQuote(getQuoteInput(candidate), new AbortController().signal),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[FundingProvider.ProviderPayloadError]`)
+  })
+
+  test('rejects invalid Stargate configuration', () => {
+    expect(() =>
+      Stargate.stargate({
+        apiKey: '',
+        userAddress: '0x1111111111111111111111111111111111111111',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(`[FundingProvider.ProviderConfigurationError]`)
+  })
+
   test('maps successful Symbiosis quotes to available quote results', async () => {
     const requests: RecordedRequest[] = []
     const candidate = quoteCandidate('symbiosis')
@@ -961,6 +1086,32 @@ describe('funding providers', () => {
     })
   })
 
+  test('returns bounded Stargate failure diagnostics', async () => {
+    const candidate = quoteCandidate('stargate')
+    const provider = Stargate.stargate({
+      apiKey: 'layerzero-api-key',
+      fetch: recordingFetch([], async () => jsonResponse({ message: 'Unauthorized' }, 401)),
+      now,
+      userAddress: '0x1111111111111111111111111111111111111111',
+    })
+    const cause = await provider
+      .getQuote(getQuoteInput(candidate), new AbortController().signal)
+      .catch((error: unknown) => error)
+
+    expect(
+      FundingProvider.failure({
+        cause,
+        operation: 'getQuote',
+        provider: getProvider('stargate'),
+      }),
+    ).toEqual({
+      failure: 'http',
+      id: 'stargate',
+      operation: 'getQuote',
+      status: 401,
+    })
+  })
+
   test('returns bounded Symbiosis failure diagnostics', () => {
     expect(
       FundingProvider.failure({
@@ -1059,6 +1210,40 @@ function squidQuote(candidate: FundingProvider.getQuote.Parameters['candidate'])
   }
 }
 
+function stargateQuotes(candidate: FundingProvider.getQuote.Parameters['candidate']) {
+  return {
+    error: null,
+    quotes: [
+      {
+        dstAmount: '999900',
+        dstAmountMin: '999800',
+        duration: { estimated: '10000' },
+        id: 'quote-cctp',
+        routeSteps: [{ srcChainKey: 'base', type: 'CCTP' }],
+        srcAmount: candidate.sourceAmount.amount,
+      },
+      {
+        dstAmount: '999500',
+        dstAmountMin: '999000',
+        duration: { estimated: '27600' },
+        expiresAt: '2026-01-01T00:01:00.000Z',
+        id: 'quote-stargate-taxi',
+        routeSteps: [{ srcChainKey: 'base', type: 'STARGATE_V2_TAXI' }],
+        srcAmount: candidate.sourceAmount.amount,
+      },
+      {
+        dstAmount: '999600',
+        dstAmountMin: '999100',
+        duration: { estimated: '258899.99999999997' },
+        expiresAt: '2026-01-01T00:01:00.000Z',
+        id: 'quote-stargate-bus',
+        routeSteps: [{ srcChainKey: 'base', type: 'STARGATE_V2_BUS' }],
+        srcAmount: candidate.sourceAmount.amount,
+      },
+    ],
+  }
+}
+
 function symbiosisQuote(candidate: FundingProvider.getQuote.Parameters['candidate']) {
   const source =
     candidate.sourceChain.kind === 'tron'

package/src/internal/funding/providers/stargate.ts

@@ -0,0 +1,184 @@
+import { Address } from 'ox'
+import * as z from 'zod/mini'
+
+import * as FundingProvider from '../Provider.js'
+
+const defaultBaseUrl = 'https://transfer.layerzero-api.com/v1'
+const defaultFetch: FundingProvider.Fetch = (input, init) => globalThis.fetch(input, init)
+const sourceDetails = {
+  STARGATE_V2_BUS: 'stargate:value-transfer-v1:bus',
+  STARGATE_V2_TAXI: 'stargate:value-transfer-v1:taxi',
+} as const
+
+namespace schema {
+  const DecimalString = z.string().check(z.regex(/^\d+(\.\d+)?$/))
+  const IntegerString = z.string().check(z.regex(/^\d+$/))
+
+  const Quote = z.object({
+    dstAmount: IntegerString,
+    dstAmountMin: IntegerString,
+    duration: z.optional(
+      z.object({
+        estimated: z.nullable(DecimalString),
+      }),
+    ),
+    expiresAt: z.optional(z.iso.datetime()),
+    id: z.string().check(z.minLength(1)),
+    routeSteps: z
+      .array(
+        z.object({
+          srcChainKey: z.string(),
+          type: z.string(),
+        }),
+      )
+      .check(z.minLength(1)),
+    srcAmount: IntegerString,
+  })
+
+  const Error = z.object({
+    message: z.string(),
+    status: z.union([z.string(), z.number()]),
+  })
+
+  export const Quotes = z.object({
+    error: z.optional(z.nullable(Error)),
+    quotes: z.array(Quote),
+  })
+}
+
+/** Creates a Stargate funding provider backed by LayerZero's `/quotes` endpoint. */
+export function stargate(options: stargate.Options) {
+  if (options.apiKey.trim().length === 0) throw new FundingProvider.ProviderConfigurationError()
+  if (!Address.validate(options.userAddress, { strict: false }))
+    throw new FundingProvider.ProviderConfigurationError()
+
+  const endpoint = new URL(options.baseUrl ?? defaultBaseUrl)
+  endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, '')}/quotes`
+  const fetch = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+
+  return FundingProvider.from({
+    id: 'stargate',
+    name: 'Stargate',
+    async getQuote({ candidate, route }, signal) {
+      const response = await FundingProvider.requestJson(endpoint, {
+        body: {
+          amount: candidate.sourceAmount.amount,
+          dstChainKey: route.destination.chain.slug,
+          dstTokenAddress: candidate.destinationToken.address,
+          dstWalletAddress: options.userAddress,
+          options: { amountType: 'EXACT_SRC_AMOUNT' },
+          srcChainKey: route.source.chain.slug,
+          srcTokenAddress: candidate.sourceToken.address,
+          srcWalletAddress: options.userAddress,
+        },
+        fetch,
+        headers: { 'user-agent': 'tempo-api', 'x-api-key': options.apiKey },
+        method: 'POST',
+        signal,
+      })
+      const parsed = schema.Quotes.safeParse(response)
+      if (!parsed.success || parsed.data.error) throw new FundingProvider.ProviderPayloadError()
+
+      const sampledAt = now()
+      const selected = selectQuote(parsed.data.quotes, {
+        amount: candidate.sourceAmount.amount,
+        now: sampledAt,
+        sourceChainKey: route.source.chain.slug,
+      })
+      if (!selected)
+        return FundingProvider.unavailableResult({
+          detail: 'stargate:value-transfer-v1',
+          message: 'NO_STARGATE_ROUTE',
+          now: sampledAt,
+          source: 'providerQuote',
+        })
+
+      const estimated = estimatedSeconds(selected.quote.duration?.estimated)
+      return {
+        ...(selected.quote.expiresAt ? { expiresAt: selected.quote.expiresAt } : {}),
+        destinationAmountMin: selected.quote.dstAmountMin,
+        destinationAmount: selected.quote.dstAmount,
+        quality: {
+          ...(estimated === undefined ? {} : { estimatedSeconds: estimated }),
+          liquiditySource: 'providerQuote',
+          sourceDetail: sourceDetails[selected.type],
+          tier: 'liquid',
+        },
+        sampledAt: sampledAt.toISOString(),
+        status: 'available',
+      }
+    },
+  })
+}
+
+export declare namespace stargate {
+  /** Stargate provider options. */
+  type Options = {
+    /** LayerZero Value Transfer API key sent in the required request header. */
+    apiKey: string
+    /** Override for tests or LayerZero test environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: FundingProvider.Fetch | undefined
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+    /** Quote wallet address used as the LayerZero sender and recipient. */
+    userAddress: string
+  }
+}
+
+function selectQuote(
+  quotes: z.output<typeof schema.Quotes>['quotes'],
+  options: selectQuote.Options,
+) {
+  return quotes
+    .flatMap((quote) => {
+      const type = quote.routeSteps
+        .filter((step) => step.srcChainKey === options.sourceChainKey)
+        .map((step) => step.type)
+        .find(isStargateType)
+      if (!type) return []
+      if (
+        quote.expiresAt !== undefined &&
+        new Date(quote.expiresAt).getTime() <= options.now.getTime()
+      )
+        return []
+      if (
+        quote.srcAmount !== options.amount ||
+        BigInt(quote.dstAmount) <= 0n ||
+        BigInt(quote.dstAmountMin) <= 0n ||
+        BigInt(quote.dstAmountMin) > BigInt(quote.dstAmount)
+      )
+        throw new FundingProvider.ProviderPayloadError()
+      return [{ quote, type }]
+    })
+    .sort((a, b) => {
+      const delta = BigInt(b.quote.dstAmountMin) - BigInt(a.quote.dstAmountMin)
+      if (delta > 0n) return 1
+      if (delta < 0n) return -1
+      return 0
+    })[0]
+}
+
+declare namespace selectQuote {
+  type Options = {
+    amount: string
+    now: Date
+    sourceChainKey: string
+  }
+}
+
+function isStargateType(type: string): type is keyof typeof sourceDetails {
+  return Object.hasOwn(sourceDetails, type)
+}
+
+function estimatedSeconds(milliseconds: string | null | undefined) {
+  if (milliseconds === undefined || milliseconds === null) return undefined
+  const [whole = '0', fraction] = milliseconds.split('.')
+  const roundedMilliseconds =
+    BigInt(whole) + (fraction !== undefined && /[1-9]/.test(fraction) ? 1n : 0n)
+  const seconds = (roundedMilliseconds + 999n) / 1_000n
+  if (seconds > BigInt(Number.MAX_SAFE_INTEGER)) throw new FundingProvider.ProviderPayloadError()
+  return Number(seconds)
+}

package/src/providers/index.test.ts

@@ -7,6 +7,7 @@ test('exports provider factories', () => {
       "relay",
       "rhino",
       "squid",
+      "stargate",
       "symbiosis",
       "uniswap",
     ]

package/src/providers/index.ts

@@ -3,6 +3,7 @@ import * as Across from '../internal/funding/providers/across.js'
 import * as Relay from '../internal/funding/providers/relay.js'
 import * as Rhino from '../internal/funding/providers/rhino.js'
 import * as Squid from '../internal/funding/providers/squid.js'
+import * as Stargate from '../internal/funding/providers/stargate.js'
 import * as Symbiosis from '../internal/funding/providers/symbiosis.js'
 
 /** Creates an Across funding provider. */
@@ -37,6 +38,14 @@ export declare namespace squid {
   type Options = Squid.squid.Options
 }
 
+/** Creates a Stargate funding provider. */
+export const stargate = Stargate.stargate
+
+export declare namespace stargate {
+  /** Stargate provider configuration. */
+  type Options = Stargate.stargate.Options
+}
+
 /** Creates a Symbiosis funding provider. */
 export const symbiosis = Symbiosis.symbiosis