tapimo 0.7.1 → 0.8.0

package/src/internal/exchange/Provider.test.ts

@@ -0,0 +1,216 @@
+import * as core_Provider from '../Provider.js'
+import * as Provider from './Provider.js'
+
+describe('from', () => {
+  test('preserves provider identity and adds the exchange category', () => {
+    const provider = Provider.from({
+      id: 'example',
+      name: 'Example',
+      async quote() {
+        throw new Provider.RouteUnavailableError()
+      },
+    })
+
+    expect(provider).toMatchObject({
+      id: 'example',
+      name: 'Example',
+      type: 'exchange',
+    })
+  })
+
+  test('rejects provider ids that are not normalized', () => {
+    expect(() =>
+      Provider.from({
+        id: ' Example ',
+        name: 'Example',
+        async quote() {
+          throw new Provider.RouteUnavailableError()
+        },
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[ExchangeProvider.ProviderConfigurationError: Provider ids must be lowercase and trimmed.]`,
+    )
+  })
+})
+
+describe('is', () => {
+  test('accepts only exchange providers with quote capability', () => {
+    const exchange = Provider.from({
+      id: 'exchange',
+      name: 'Exchange',
+      async quote() {
+        throw new Provider.RouteUnavailableError()
+      },
+    })
+    const incomplete = core_Provider.from({
+      id: 'incomplete',
+      name: 'Incomplete',
+      type: 'exchange',
+    })
+    const funding = core_Provider.from({ id: 'funding', name: 'Funding', type: 'funding' })
+
+    expect([exchange, incomplete, funding].map(Provider.is)).toEqual([true, false, false])
+  })
+})
+
+describe('failure', () => {
+  const provider = Provider.from({
+    id: 'example',
+    name: 'Example',
+    async quote() {
+      throw new Provider.RouteUnavailableError()
+    },
+  })
+
+  test('reports the upstream operation and status', () => {
+    expect(
+      Provider.failure(
+        new Provider.ProviderResponseError({ operation: 'check_approval', status: 429 }),
+        { chainId: 4217, operation: 'quote', provider },
+      ),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "failure": "rate_limit",
+        "id": "example",
+        "operation": "check_approval",
+        "status": 429,
+      }
+    `)
+  })
+
+  test('reports payload failures at the enclosing operation', () => {
+    expect(
+      Provider.failure(new Provider.ProviderPayloadError(), {
+        chainId: 4217,
+        operation: 'finalize',
+        provider,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "failure": "payload",
+        "id": "example",
+        "operation": "finalize",
+      }
+    `)
+  })
+
+  test('reports bounded payload validation codes', () => {
+    expect(
+      Provider.failure(new Provider.ProviderPayloadError({ code: 'quote.response.permitData' }), {
+        chainId: 4217,
+        operation: 'quote',
+        provider,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "code": "quote.response.permitData",
+        "failure": "payload",
+        "id": "example",
+        "operation": "quote",
+      }
+    `)
+  })
+
+  test('reports the upstream operation for network failures', () => {
+    expect(
+      Provider.failure(
+        new Provider.ProviderNetworkError({
+          cause: new TypeError('secret network detail'),
+          operation: 'check_approval',
+        }),
+        { chainId: 4217, operation: 'quote', provider },
+      ),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "failure": "network",
+        "id": "example",
+        "operation": "check_approval",
+      }
+    `)
+  })
+
+  test('ignores failures outside the provider boundary', () => {
+    expect(
+      Provider.failure(new Error('metadata lookup failed'), {
+        chainId: 4217,
+        operation: 'quote',
+        provider,
+      }),
+    ).toBeUndefined()
+  })
+})
+
+describe('validateExecution', () => {
+  const account = '0x1111111111111111111111111111111111111111'
+  const destinationToken = '0x20c0000000000000000000000000000000000002'
+  const sourceToken = '0x20c0000000000000000000000000000000000001'
+  const router = '0x2222222222222222222222222222222222222222'
+
+  test('accepts transfers within exact-source bounds', () => {
+    expect(() =>
+      Provider.validateExecution({
+        account,
+        execution: {
+          destinationAmount: '100',
+          destinationToken,
+          gasUnits: '1',
+          minimumDestinationAmount: '99',
+          mode: 'exactSource',
+          sourceAmount: '50',
+          sourceToken,
+        },
+        transfers: [
+          { amount: 50n, from: account, to: router, token: sourceToken },
+          { amount: 99n, from: router, to: account, token: destinationToken },
+        ],
+      }),
+    ).not.toThrow()
+  })
+
+  test('rejects a different outgoing token', () => {
+    expect(() =>
+      Provider.validateExecution({
+        account,
+        execution: {
+          destinationAmount: '100',
+          destinationToken,
+          gasUnits: '1',
+          minimumDestinationAmount: '99',
+          mode: 'exactSource',
+          sourceAmount: '50',
+          sourceToken,
+        },
+        transfers: [
+          { amount: 1n, from: account, to: router, token: destinationToken },
+          { amount: 50n, from: account, to: router, token: sourceToken },
+          { amount: 100n, from: router, to: account, token: destinationToken },
+        ],
+      }),
+    ).toThrow(Provider.ProviderPayloadError)
+  })
+
+  test('rejects execution outside exact-destination bounds', () => {
+    expect(() =>
+      Provider.validateExecution({
+        account,
+        execution: {
+          destinationAmount: '100',
+          destinationToken,
+          gasUnits: '1',
+          maximumSourceAmount: '50',
+          mode: 'exactDestination',
+          sourceAmount: '49',
+          sourceToken,
+        },
+        transfers: [
+          { amount: 51n, from: account, to: router, token: sourceToken },
+          { amount: 100n, from: router, to: account, token: destinationToken },
+        ],
+      }),
+    ).toThrow(Provider.ProviderPayloadError)
+  })
+})

package/src/internal/exchange/Provider.ts

@@ -0,0 +1,326 @@
+import type { Hex } from 'ox'
+
+import * as core_Provider from '../Provider.js'
+import type * as Log from '../Log.js'
+
+/** Exchange quote provider called after the native DEX cannot route a swap. */
+export type Provider<id extends string = string> = core_Provider.Provider<id, 'exchange'> & {
+  /** Converts a signed continuation into final executable calls. */
+  finalizeQuote?(
+    this: void,
+    input: FinalizeQuoteInput,
+    signal: AbortSignal,
+  ): Promise<FinalizeQuoteResult>
+  /** Returns the approvals, signature, or executable calls needed to continue. */
+  quote(this: void, input: QuoteInput, signal: AbortSignal): Promise<QuoteResult>
+}
+
+/** Provider-neutral unsigned transaction call. */
+export type Call = {
+  /** ABI-encoded call data. */
+  data: Hex.Hex
+  /** Contract receiving the call. */
+  to: `0x${string}`
+  /** Native token value as a JSON-RPC quantity. */
+  value: Hex.Hex
+}
+
+/** Input used to finish a provider quote after signing. */
+export type FinalizeQuoteInput = {
+  /** Wallet signing and executing the swap. */
+  account: `0x${string}`
+  /** Tempo chain id. */
+  chainId: number
+  /** Opaque provider state returned by `quote`. */
+  continuation: string
+  /** EIP-712 signature requested by the quote result. */
+  signature: Hex.Hex
+}
+
+/** Final executable calls returned after a signature. */
+export type FinalizeQuoteResult = {
+  /** Calls to execute in order. */
+  calls: readonly Call[]
+  /** Quote constraints that the final calls must satisfy. */
+  execution: Execution
+}
+
+/** Constraints used to validate executable provider calls. */
+export type Execution = QuoteAmounts & {
+  /** Token received by the swap. */
+  destinationToken: `0x${string}`
+  /** Side whose requested amount remains exact. */
+  mode: 'exactDestination' | 'exactSource'
+  /** Token spent by the swap. */
+  sourceToken: `0x${string}`
+}
+
+/** Token movement observed while simulating provider calls. */
+export type Transfer = {
+  /** Amount moved in base units. */
+  amount: bigint
+  /** Account sending the tokens. */
+  from: `0x${string}`
+  /** Account receiving the tokens. */
+  to: `0x${string}`
+  /** Token contract that emitted the transfer. */
+  token: `0x${string}`
+}
+
+/** Provider-neutral quote input. */
+export type QuoteInput = {
+  /** Wallet receiving and executing the swap. */
+  account: `0x${string}`
+  /** Exact source or destination amount in base units. */
+  amount: string
+  /** Tempo chain id. */
+  chainId: number
+  /** Token received by the swap. */
+  destinationToken: `0x${string}`
+  /** Side whose requested amount remains exact. */
+  mode: 'exactDestination' | 'exactSource'
+  /** Maximum execution slippage in basis points. */
+  slippageBps: number
+  /** Token spent by the swap. */
+  sourceToken: `0x${string}`
+}
+
+/** Quote with the approvals, signature, or transaction needed for its next step. */
+export type QuoteResult =
+  | (QuoteAmounts & {
+      /** Calls that must confirm before requesting a fresh quote. */
+      approval: { calls: readonly Call[] }
+      /** Onchain approval is required before this swap can be quoted for execution. */
+      status: 'approvalRequired'
+    })
+  | (QuoteAmounts & {
+      /** Quote is ready for execution. */
+      status: 'ready'
+      /** Ordered calls required to execute the quote. */
+      transaction: { calls: readonly Call[] }
+    })
+  | (QuoteAmounts & {
+      /** Opaque provider state passed to `finalizeQuote`. */
+      continuation: string
+      /** Quote needs a wallet signature before final calldata can be built. */
+      status: 'signatureRequired'
+      /** EIP-712 payload the wallet must sign. */
+      typedData: TypedData
+    })
+
+/** Defines an exchange provider while preserving its concrete identity. */
+export function from<const id extends string>(options: from.Options<id>): Provider<id> {
+  if (options.id !== options.id.trim().toLowerCase() || options.id.length === 0)
+    throw new ProviderConfigurationError('Provider ids must be lowercase and trimmed.')
+  return core_Provider.from({ ...options, type: 'exchange' })
+}
+
+export declare namespace from {
+  /** Exchange provider definition. */
+  type Options<id extends string> = Omit<Provider<id>, 'type'>
+}
+
+/** Returns whether a registered provider implements exchange quotes. */
+export function is(provider: core_Provider.Provider): provider is Provider {
+  return provider.type === 'exchange' && 'quote' in provider && typeof provider.quote === 'function'
+}
+
+/** Returns bounded exchange-provider failure details for structured request logs. */
+export function failure(cause: unknown, options: failure.Options): Log.ProviderFailure | undefined {
+  const { chainId, operation, provider } = options
+  if (cause instanceof ProviderResponseError)
+    return {
+      chainId,
+      failure: cause.status === 429 ? 'rate_limit' : 'http',
+      id: provider.id,
+      operation: cause.operation,
+      status: cause.status,
+    }
+  if (cause instanceof ProviderNetworkError)
+    return { chainId, failure: 'network', id: provider.id, operation: cause.operation }
+  if (cause instanceof ProviderPayloadError)
+    return {
+      chainId,
+      ...(cause.code ? { code: cause.code } : {}),
+      failure: 'payload',
+      id: provider.id,
+      operation,
+    }
+  return undefined
+}
+
+export declare namespace failure {
+  /** Exchange-provider context retained when a quote operation fails. */
+  type Options = {
+    /** Chain selected by the quote request. */
+    chainId: number
+    /** Provider operation used when the error has no narrower operation. */
+    operation: string
+    /** Exchange provider that handled the request. */
+    provider: Provider
+  }
+}
+
+/** Validates simulated token movements against an executable quote. */
+export function validateExecution(options: validateExecution.Options): void {
+  const account = options.account.toLowerCase()
+  const destinationToken = options.execution.destinationToken.toLowerCase()
+  const sourceToken = options.execution.sourceToken.toLowerCase()
+  let destinationReceived = 0n
+  let sourceIncoming = 0n
+  let sourceOutgoing = 0n
+
+  for (const transfer of options.transfers) {
+    const token = transfer.token.toLowerCase()
+    if (transfer.from.toLowerCase() === account) {
+      if (token !== sourceToken) throw new ProviderPayloadError()
+      sourceOutgoing += transfer.amount
+    }
+    if (transfer.to.toLowerCase() !== account) continue
+    if (token === sourceToken) sourceIncoming += transfer.amount
+    if (token === destinationToken) destinationReceived += transfer.amount
+  }
+
+  const sourceSpent = sourceOutgoing - sourceIncoming
+  if (sourceSpent <= 0n) throw new ProviderPayloadError()
+  if (options.execution.mode === 'exactSource') {
+    if (
+      sourceSpent !== BigInt(options.execution.sourceAmount) ||
+      options.execution.minimumDestinationAmount === undefined ||
+      destinationReceived < BigInt(options.execution.minimumDestinationAmount)
+    )
+      throw new ProviderPayloadError()
+    return
+  }
+
+  if (
+    options.execution.maximumSourceAmount === undefined ||
+    sourceSpent > BigInt(options.execution.maximumSourceAmount) ||
+    destinationReceived < BigInt(options.execution.destinationAmount)
+  )
+    throw new ProviderPayloadError()
+}
+
+export declare namespace validateExecution {
+  /** Simulated transfers and quote constraints to validate. */
+  type Options = {
+    /** Wallet executing the provider calls. */
+    account: `0x${string}`
+    /** Quote constraints bound to the executable calls. */
+    execution: Execution
+    /** Token transfers emitted by the simulated calls. */
+    transfers: readonly Transfer[]
+  }
+}
+
+/** Amount bounds returned by an exchange provider. */
+export type QuoteAmounts = {
+  /** Expected destination amount in base units. */
+  destinationAmount: string
+  /** Estimated execution gas units. */
+  gasUnits: string
+  /** Maximum source amount for an exact-destination quote. */
+  maximumSourceAmount?: string | undefined
+  /** Minimum destination amount for an exact-source quote. */
+  minimumDestinationAmount?: string | undefined
+  /** Expected source amount in base units. */
+  sourceAmount: string
+}
+
+/** Provider-neutral EIP-712 payload accepted by Privy and common wallet clients. */
+export type TypedData = {
+  /** EIP-712 signing domain. */
+  domain: Record<string, unknown>
+  /** EIP-712 message values. */
+  message: Record<string, unknown>
+  /** Root EIP-712 type. */
+  primaryType: string
+  /** EIP-712 type definitions. */
+  types: Record<string, readonly { name: string; type: string }[]>
+}
+
+/** Raised when a provider has no executable route for the requested swap. */
+export class RouteUnavailableError extends Error {
+  override name = 'ExchangeProvider.RouteUnavailableError'
+}
+
+/** Raised when a continuation cannot be decoded or validated. */
+export class ProviderContinuationError extends Error {
+  override name = 'ExchangeProvider.ProviderContinuationError'
+}
+
+/** Raised when required provider configuration is invalid. */
+export class ProviderConfigurationError extends Error {
+  override name = 'ExchangeProvider.ProviderConfigurationError'
+}
+
+/** Raised when an upstream provider request fails before receiving a response. */
+export class ProviderNetworkError extends Error {
+  override name = 'ExchangeProvider.ProviderNetworkError'
+
+  /** Upstream operation that failed. */
+  operation: string
+
+  constructor(options: ProviderNetworkError.Options) {
+    super(`Provider ${options.operation} request failed`, { cause: options.cause })
+    this.operation = options.operation
+  }
+}
+
+export declare namespace ProviderNetworkError {
+  /** Safe request details retained for operational reporting. */
+  type Options = {
+    /** Original network error. */
+    cause: TypeError
+    /** Stable upstream operation identifier. */
+    operation: string
+  }
+}
+
+/** Raised when an upstream provider returns an invalid payload. */
+export class ProviderPayloadError extends Error {
+  override name = 'ExchangeProvider.ProviderPayloadError'
+
+  /** Stable validation code safe for operational reporting. */
+  code?: string | undefined
+
+  constructor(options: ProviderPayloadError.Options = {}) {
+    super(options.code ? `Provider payload failed ${options.code}` : undefined)
+    this.code = options.code
+  }
+}
+
+export declare namespace ProviderPayloadError {
+  /** Bounded invalid-payload details. */
+  type Options = {
+    /** Stable validation code safe for operational reporting. */
+    code?: string | undefined
+  }
+}
+
+/** Raised when an upstream provider request fails. */
+export class ProviderResponseError extends Error {
+  override name = 'ExchangeProvider.ProviderResponseError'
+
+  /** Upstream operation that returned the response. */
+  operation: string
+
+  /** Upstream HTTP status. */
+  status: number
+
+  constructor(options: ProviderResponseError.Options) {
+    super(`Provider ${options.operation} request failed with status ${options.status}`)
+    this.operation = options.operation
+    this.status = options.status
+  }
+}
+
+export declare namespace ProviderResponseError {
+  /** Safe upstream response details retained for operational reporting. */
+  type Options = {
+    /** Stable upstream operation identifier. */
+    operation: string
+    /** Upstream HTTP status. */
+    status: number
+  }
+}

package/src/internal/exchange/index.test.ts

@@ -0,0 +1,6 @@
+import * as Exchange from './index.js'
+
+test('exports the exchange provider contract', () => {
+  expect(Exchange.Provider.from).toBeTypeOf('function')
+  expect(Exchange.Provider.is).toBeTypeOf('function')
+})

package/src/internal/exchange/index.ts

@@ -0,0 +1 @@
+export * as Provider from './Provider.js'

package/src/internal/exchange/providers/uniswap.test.ts

@@ -0,0 +1,122 @@
+import { Hex } from 'ox'
+import { encodeAbiParameters, encodeFunctionData, parseAbi, parseAbiParameters } from 'viem'
+
+import * as Provider from '../Provider.js'
+import {
+  uniswap,
+  validateApprovalResponse,
+  validateExactSourceMaximum,
+  validateExactSourceMinimum,
+  validateRouterCalldata,
+} from './uniswap.js'
+
+const routerAbi = parseAbi([
+  'function execute(bytes commands, bytes[] inputs)',
+  'function execute(bytes commands, bytes[] inputs, uint256 deadline)',
+])
+
+const execute = (commands: `0x${string}`, inputs: readonly `0x${string}`[]) =>
+  encodeFunctionData({
+    abi: routerAbi,
+    args: [commands, inputs],
+    functionName: 'execute',
+  })
+
+describe('uniswap', () => {
+  test('creates an exchange provider', () => {
+    expect(uniswap({ apiKey: 'uniswap-key' })).toMatchObject({
+      id: 'uniswap',
+      name: 'Uniswap',
+      type: 'exchange',
+    })
+  })
+
+  test('rejects a blank API key', () => {
+    expect(() => uniswap({ apiKey: ' ' })).toThrow(Provider.ProviderConfigurationError)
+  })
+})
+
+describe('validateApprovalResponse', () => {
+  test('accepts hex transaction values', () => {
+    expect(
+      validateApprovalResponse({
+        approval: {
+          chainId: 4217,
+          data: '0x1234',
+          from: `0x${'11'.repeat(20)}`,
+          to: `0x${'22'.repeat(20)}`,
+          value: '0x0',
+        },
+        cancel: null,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "approval": {
+          "chainId": 4217,
+          "data": "0x1234",
+          "from": "0x1111111111111111111111111111111111111111",
+          "to": "0x2222222222222222222222222222222222222222",
+          "value": "0x0",
+        },
+        "cancel": null,
+      }
+    `)
+  })
+})
+
+describe('validateRouterCalldata', () => {
+  test('accepts swap commands and nested plans', () => {
+    const nested = encodeAbiParameters(parseAbiParameters('bytes, bytes[]'), ['0x00', ['0x']])
+    expect(() => validateRouterCalldata(execute('0x0021', ['0x', nested]))).not.toThrow()
+  })
+
+  test('accepts supported V4 swap actions', () => {
+    const plan = encodeAbiParameters(parseAbiParameters('bytes, bytes[]'), ['0x060e', ['0x', '0x']])
+    expect(() => validateRouterCalldata(execute('0x10', [plan]))).not.toThrow()
+  })
+
+  test('rejects unsupported commands and mismatched inputs', () => {
+    expect(() => validateRouterCalldata(execute('0x11', ['0x']))).toThrow(
+      Provider.ProviderPayloadError,
+    )
+    expect(() =>
+      validateRouterCalldata(execute(Hex.fromBytes(new Uint8Array([0x00])), [])),
+    ).toThrow(Provider.ProviderPayloadError)
+  })
+})
+
+describe('validateExactSourceMaximum', () => {
+  test('accepts an absent or equal maximum', () => {
+    expect(() => validateExactSourceMaximum({ amount: '100' })).not.toThrow()
+    expect(() => validateExactSourceMaximum({ amount: '100', maximumAmount: '100' })).not.toThrow()
+  })
+
+  test('rejects a larger or smaller maximum', () => {
+    expect(() => validateExactSourceMaximum({ amount: '100', maximumAmount: '101' })).toThrow(
+      Provider.ProviderPayloadError,
+    )
+    expect(() => validateExactSourceMaximum({ amount: '100', maximumAmount: '99' })).toThrow(
+      Provider.ProviderPayloadError,
+    )
+  })
+})
+
+describe('validateExactSourceMinimum', () => {
+  test('accepts the integer slippage floor', () => {
+    expect(() =>
+      validateExactSourceMinimum({ amount: '101', minimumAmount: '100', slippageBps: 50 }),
+    ).not.toThrow()
+  })
+
+  test('rejects missing, excessive, or insufficient minimums', () => {
+    expect(() => validateExactSourceMinimum({ amount: '101', slippageBps: 50 })).toThrow(
+      Provider.ProviderPayloadError,
+    )
+    expect(() =>
+      validateExactSourceMinimum({ amount: '101', minimumAmount: '99', slippageBps: 50 }),
+    ).toThrow(Provider.ProviderPayloadError)
+    expect(() =>
+      validateExactSourceMinimum({ amount: '101', minimumAmount: '102', slippageBps: 50 }),
+    ).toThrow(Provider.ProviderPayloadError)
+  })
+})