tapimo 0.11.0 → 0.13.0

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

@@ -0,0 +1,409 @@
+import { AbiFunction, Address, Hex, RpcTransport } from 'ox'
+import { createClient, custom, fallback, publicActions } from 'viem'
+import * as z from 'zod/mini'
+
+import * as Action from '../Action.js'
+import type * as Catalog from '../Catalog.js'
+import * as FundingProvider from '../Provider.js'
+
+const approve = AbiFunction.from('function approve(address spender, uint256 amount)')
+const defaultFetch: FundingProvider.Fetch = (input, init) => globalThis.fetch(input, init)
+const destinationChainId = 'eip155:4217'
+const destinationEid = 30_410
+const destinationToken = '0x20C000000000000000000000b9537d11c60E8b50'
+const quoteOft = AbiFunction.from(
+  'function quoteOFT((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam) view returns ((uint256 minAmountLD, uint256 maxAmountLD) limit, (int256 feeAmountLD, string description)[] oftFeeDetails, (uint256 amountSentLD, uint256 amountReceivedLD) receipt)',
+)
+const quoteSend = AbiFunction.from(
+  'function quoteSend((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam, bool payInLzToken) view returns ((uint256 nativeFee, uint256 lzTokenFee) fee)',
+)
+const sendToken = AbiFunction.from(
+  'function sendToken((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam, (uint256 nativeFee, uint256 lzTokenFee) fee, address refundAddress) payable returns ((bytes32 guid, uint64 nonce, (uint256 nativeFee, uint256 lzTokenFee) fee) msgReceipt, (uint256 amountSentLD, uint256 amountReceivedLD) oftReceipt, (uint72 ticketId, bytes passengerBytes) ticket)',
+)
+const quoteTtlMs = 60_000
+const zeroAddress = '0x0000000000000000000000000000000000000000'
+
+const configuration = z
+  .strictObject({
+    poolAddress: z
+      .string()
+      .check(
+        z.regex(/^0x[0-9a-fA-F]{40}$/),
+        z.describe('Stargate pool contract on the source chain.'),
+      ),
+  })
+  .check(z.describe('Stargate configuration for one funding route.'))
+
+type Deployment = {
+  pool: Address.Address
+  sourceToken: Address.Address
+}
+
+type SendParam = {
+  amountLD: bigint
+  composeMsg: Hex.Hex
+  dstEid: number
+  extraOptions: Hex.Hex
+  minAmountLD: bigint
+  oftCmd: Hex.Hex
+  to: Hex.Hex
+}
+
+/** Creates a direct Stargate V2 OFT funding provider. */
+export function stargate(options: stargate.Options = {}) {
+  const fetch = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+
+  return FundingProvider.from({
+    id: 'stargate',
+    name: 'Stargate',
+    async getQuote({ candidate, route }, signal) {
+      const deployment = resolveDeployment({
+        configuration: candidate.configuration,
+        destinationChainId: route.destination.chain.id,
+        destinationTokenAddress: route.destination.address,
+        sourceChainId: route.source.chain.id,
+        sourceTokenAddress: route.source.address,
+      })
+      const sampledAt = now()
+      if (!deployment) return unavailable({ message: 'ROUTE_NOT_CONFIGURED', now: sampledAt })
+
+      const sendParam = createSendParam({
+        amount: candidate.sourceAmount.amount,
+        recipient: zeroAddress,
+      })
+      const [limit, feeDetails, receipt] = await client({ fetch, route, signal }).readContract({
+        abi: [quoteOft],
+        address: deployment.pool,
+        args: [sendParam],
+        functionName: 'quoteOFT',
+      })
+      if (!isExactQuote({ amount: candidate.sourceAmount.amount, feeDetails, limit, receipt }))
+        return unavailable({ message: 'NO_EXACT_ROUTE', now: sampledAt })
+
+      return {
+        destinationAmountMin: receipt.amountReceivedLD.toString(),
+        destinationAmount: receipt.amountReceivedLD.toString(),
+        quality: quality(),
+        sampledAt: sampledAt.toISOString(),
+        status: 'available',
+      }
+    },
+    async prepareTransfer({ candidate, method, mode, recipient, sender }, signal) {
+      if (
+        method !== 'transaction' ||
+        mode !== 'exactSource' ||
+        !Address.validate(recipient, { strict: false }) ||
+        !Address.validate(sender, { strict: false })
+      )
+        throw new FundingProvider.ProviderConfigurationError()
+
+      const deployment = resolveDeployment({
+        configuration: candidate.configuration,
+        destinationChainId: candidate.destinationChain.id,
+        destinationTokenAddress: candidate.destinationToken.address,
+        sourceChainId: candidate.sourceChain.id,
+        sourceTokenAddress: candidate.sourceToken.address,
+      })
+      if (!deployment) throw new FundingProvider.ProviderUnavailableError()
+      const sendParam = createSendParam({ amount: candidate.sourceAmount.amount, recipient })
+      const rpc = client({ fetch, route: candidate.route, signal })
+      const [[limit, feeDetails, receipt], messagingFee] = await Promise.all([
+        rpc.readContract({
+          abi: [quoteOft],
+          address: deployment.pool,
+          args: [sendParam],
+          functionName: 'quoteOFT',
+        }),
+        rpc.readContract({
+          abi: [quoteSend],
+          account: sender as Address.Address,
+          address: deployment.pool,
+          args: [sendParam, false],
+          functionName: 'quoteSend',
+        }),
+      ])
+      if (!isExactQuote({ amount: candidate.sourceAmount.amount, feeDetails, limit, receipt }))
+        throw new FundingProvider.ProviderUnavailableError()
+      if (messagingFee.lzTokenFee !== 0n) throw new FundingProvider.ProviderPayloadError()
+
+      const action = {
+        calls: [
+          {
+            data: AbiFunction.encodeData(approve, [
+              deployment.pool,
+              BigInt(candidate.sourceAmount.amount),
+            ]),
+            to: deployment.sourceToken,
+            value: '0x0',
+          },
+          {
+            data: AbiFunction.encodeData(sendToken, [sendParam, messagingFee, sender]),
+            to: deployment.pool,
+            value: Hex.fromNumber(messagingFee.nativeFee),
+          },
+        ],
+        type: 'evm:calls' as const,
+      }
+      validateAction({
+        action,
+        configuration: candidate.configuration,
+        destinationTokenAddress: candidate.destinationToken.address,
+        recipient,
+        sender,
+        sourceAmount: candidate.sourceAmount.amount,
+        sourceChainId: candidate.sourceChain.id,
+        sourceTokenAddress: candidate.sourceToken.address,
+      })
+
+      const sampledAt = now()
+      return {
+        action,
+        destinationAmountMin: receipt.amountReceivedLD.toString(),
+        destinationAmount: receipt.amountReceivedLD.toString(),
+        expiresAt: new Date(sampledAt.getTime() + quoteTtlMs).toISOString(),
+        fees:
+          messagingFee.nativeFee === 0n
+            ? []
+            : [
+                {
+                  amount: messagingFee.nativeFee.toString(),
+                  side: 'source' as const,
+                  token: nativeToken(candidate.sourceChain.id),
+                },
+              ],
+        quality: quality(),
+        sampledAt: sampledAt.toISOString(),
+      }
+    },
+    validateTransferAction({ action, candidate, recipient, sender }) {
+      return {
+        nativeValues: validateAction({
+          action,
+          configuration: candidate.configuration,
+          destinationTokenAddress: candidate.destinationToken.address,
+          recipient,
+          sender,
+          sourceAmount: candidate.sourceAmount.amount,
+          sourceChainId: candidate.sourceChain.id,
+          sourceTokenAddress: candidate.sourceToken.address,
+        }),
+      }
+    },
+  })
+}
+
+export declare namespace stargate {
+  /** Stargate provider options. */
+  type Options = {
+    /** Fetch implementation override for chain RPC requests. */
+    fetch?: FundingProvider.Fetch | undefined
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+  }
+}
+
+/** Validates one direct Stargate action and returns its exact native-value allowance. */
+export function validateAction(options: validateAction.Options): readonly Action.NativeValue[] {
+  try {
+    const action = Action.schema.EvmCalls.parse(options.action)
+    const deployment = resolveDeployment({
+      configuration: options.configuration,
+      destinationChainId,
+      destinationTokenAddress: options.destinationTokenAddress,
+      sourceChainId: options.sourceChainId,
+      sourceTokenAddress: options.sourceTokenAddress,
+    })
+    if (!deployment || action.calls.length !== 2) throw new FundingProvider.ProviderPayloadError()
+    const [approval, execution] = action.calls
+    if (
+      !Address.isEqual(approval!.to as Address.Address, deployment.sourceToken) ||
+      BigInt(approval!.value) !== 0n ||
+      !Address.isEqual(execution!.to as Address.Address, deployment.pool)
+    )
+      throw new FundingProvider.ProviderPayloadError()
+
+    const [spender, approvalAmount] = AbiFunction.decodeData(approve, approval!.data as Hex.Hex)
+    const [sendParam, messagingFee, refundAddress] = AbiFunction.decodeData(
+      sendToken,
+      execution!.data as Hex.Hex,
+    )
+    const nativeValue = BigInt(execution!.value)
+    if (
+      !Address.isEqual(spender, deployment.pool) ||
+      approvalAmount !== BigInt(options.sourceAmount) ||
+      sendParam.amountLD !== BigInt(options.sourceAmount) ||
+      sendParam.composeMsg !== '0x' ||
+      sendParam.dstEid !== destinationEid ||
+      sendParam.extraOptions !== '0x' ||
+      sendParam.minAmountLD !== BigInt(options.sourceAmount) ||
+      sendParam.oftCmd !== '0x' ||
+      !Hex.isEqual(sendParam.to, recipientBytes32(options.recipient)) ||
+      messagingFee.lzTokenFee !== 0n ||
+      messagingFee.nativeFee !== nativeValue ||
+      !Address.isEqual(refundAddress, options.sender as Address.Address)
+    )
+      throw new FundingProvider.ProviderPayloadError()
+    return [{ to: execution!.to, value: execution!.value }]
+  } catch (cause) {
+    if (cause instanceof FundingProvider.ProviderPayloadError) throw cause
+    throw new FundingProvider.ProviderPayloadError()
+  }
+}
+
+export declare namespace validateAction {
+  /** Expected route terms for one Stargate action. */
+  type Options = {
+    /** Prepared Stargate action. */
+    action: Action.EvmCalls
+    /** Stargate configuration for the selected route. */
+    configuration?: Catalog.Configuration | undefined
+    /** Curated Tempo destination token. */
+    destinationTokenAddress: string
+    /** Tempo beneficiary. */
+    recipient: string
+    /** Source account and LayerZero refund recipient. */
+    sender: string
+    /** Exact source amount in base units. */
+    sourceAmount: string
+    /** Source chain CAIP-2 id. */
+    sourceChainId: string
+    /** Curated source token. */
+    sourceTokenAddress: string
+  }
+}
+
+function client(options: client.Options) {
+  if (options.route.source.chain.rpcUrls.length === 0)
+    throw new FundingProvider.ProviderConfigurationError()
+  return createClient({
+    transport: fallback(
+      options.route.source.chain.rpcUrls.map((url) =>
+        custom(
+          RpcTransport.fromHttp(url, {
+            fetchFn: (input, init) => options.fetch(input, { ...init, signal: options.signal }),
+          }),
+          { retryCount: 0 },
+        ),
+      ),
+    ),
+  }).extend(publicActions)
+}
+
+declare namespace client {
+  type Options = {
+    fetch: FundingProvider.Fetch
+    route: FundingProvider.QuoteCandidate['route']
+    signal: AbortSignal
+  }
+}
+
+function createSendParam(options: createSendParam.Options): SendParam {
+  const amount = BigInt(options.amount)
+  return {
+    amountLD: amount,
+    composeMsg: '0x',
+    dstEid: destinationEid,
+    extraOptions: '0x',
+    minAmountLD: amount,
+    oftCmd: '0x',
+    to: recipientBytes32(options.recipient),
+  }
+}
+
+declare namespace createSendParam {
+  type Options = {
+    amount: string
+    recipient: string
+  }
+}
+
+function isExactQuote(options: isExactQuote.Options) {
+  const amount = BigInt(options.amount)
+  return (
+    amount >= options.limit.minAmountLD &&
+    amount <= options.limit.maxAmountLD &&
+    options.feeDetails.every((fee) => fee.feeAmountLD >= 0n) &&
+    options.receipt.amountSentLD === amount &&
+    options.receipt.amountReceivedLD === amount
+  )
+}
+
+declare namespace isExactQuote {
+  type Options = {
+    amount: string
+    feeDetails: readonly { feeAmountLD: bigint }[]
+    limit: { maxAmountLD: bigint; minAmountLD: bigint }
+    receipt: { amountReceivedLD: bigint; amountSentLD: bigint }
+  }
+}
+
+function nativeToken(sourceChainId: string) {
+  return {
+    address: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+    currency: 'ETH',
+    decimals: 18,
+    name: 'Ether',
+    standard: 'native',
+    symbol: 'ETH',
+    tokenKey: `${sourceChainId}/slip44:60`,
+    verified: true,
+  }
+}
+
+function quality() {
+  return {
+    liquiditySource: 'onchain',
+    sourceDetail: 'stargate:oft-v2:taxi',
+    tier: 'liquid' as const,
+  }
+}
+
+function recipientBytes32(recipient: string) {
+  if (!Address.validate(recipient, { strict: false }))
+    throw new FundingProvider.ProviderConfigurationError()
+  return Hex.padLeft(recipient as Hex.Hex, 32)
+}
+
+function resolveDeployment(options: resolveDeployment.Options): Deployment | undefined {
+  const parsed = configuration.safeParse(options.configuration)
+  if (
+    !parsed.success ||
+    options.destinationChainId !== destinationChainId ||
+    !options.sourceChainId.startsWith('eip155:') ||
+    !Address.validate(options.destinationTokenAddress, { strict: false }) ||
+    !Address.validate(options.sourceTokenAddress, { strict: false }) ||
+    !Address.isEqual(options.destinationTokenAddress as Address.Address, destinationToken)
+  )
+    return undefined
+  return {
+    pool: Address.checksum(parsed.data.poolAddress),
+    sourceToken: Address.checksum(options.sourceTokenAddress),
+  }
+}
+
+declare namespace resolveDeployment {
+  type Options = {
+    configuration?: Catalog.Configuration | undefined
+    destinationChainId: string
+    destinationTokenAddress: string
+    sourceChainId: string
+    sourceTokenAddress: string
+  }
+}
+
+function unavailable(options: unavailable.Options) {
+  return FundingProvider.unavailableResult({
+    detail: 'stargate:oft-v2',
+    message: options.message,
+    now: options.now,
+    source: 'onchain',
+  })
+}
+
+declare namespace unavailable {
+  type Options = {
+    message: string
+    now: Date
+  }
+}

package/src/internal/index.test.ts

@@ -12,6 +12,7 @@ test('exports internal modules', () => {
       "Errors",
       "Exchange",
       "Fees",
+      "Fetch",
       "Funding",
       "Id",
       "Idempotency",

package/src/internal/index.ts

@@ -7,6 +7,7 @@ export * as EarnVaults from './EarnVaults.js'
 export * as Errors from './Errors.js'
 export * as Exchange from './exchange/index.js'
 export * as Fees from './Fees.js'
+export * as Fetch from './Fetch.js'
 export * as Funding from './funding/index.js'
 export * as Id from './Id.js'
 export * as Idempotency from './Idempotency.js'

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