@eth-optimism/actions-sdk 0.1.0 → 0.3.0

package/src/swap/__mocks__/MockSwapProvider.ts

@@ -0,0 +1,216 @@
+import type { Address } from 'viem'
+import { type MockedFunction, vi } from 'vitest'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { MockChainManager } from '@/services/__mocks__/MockChainManager.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import { SwapProvider } from '@/swap/core/SwapProvider.js'
+import type {
+  GetSwapMarketParams,
+  GetSwapMarketsParams,
+  ResolvedSwapParams,
+  SwapMarket,
+  SwapPrice,
+  SwapPriceParams,
+  SwapProviderConfig,
+  SwapTransaction,
+} from '@/types/swap/index.js'
+
+export interface MockSwapProviderConfig {
+  supportedChains: SupportedChainId[]
+  defaultPrice: string
+  defaultPriceImpact: number
+}
+
+/**
+ * Mock Swap Provider for testing
+ */
+export class MockSwapProvider extends SwapProvider<SwapProviderConfig> {
+  public mockExecute: MockedFunction<
+    (params: ResolvedSwapParams) => Promise<SwapTransaction>
+  >
+  public mockGetPrice: MockedFunction<
+    (params: SwapPriceParams) => Promise<SwapPrice>
+  >
+  public mockGetMarket: MockedFunction<
+    (params: GetSwapMarketParams) => Promise<SwapMarket>
+  >
+  public mockGetMarkets: MockedFunction<
+    (params: GetSwapMarketsParams) => Promise<SwapMarket[]>
+  >
+
+  private _supportedChains: SupportedChainId[]
+  private mockProviderConfig: MockSwapProviderConfig
+
+  constructor(
+    config?: SwapProviderConfig,
+    mockConfig?: Partial<MockSwapProviderConfig>,
+    chainManager?: ChainManager,
+  ) {
+    super(
+      config || {},
+      chainManager || (new MockChainManager() as unknown as ChainManager),
+    )
+
+    this._supportedChains = mockConfig?.supportedChains ?? [
+      84532 as SupportedChainId,
+    ]
+    this.mockProviderConfig = {
+      supportedChains: this._supportedChains,
+      defaultPrice: mockConfig?.defaultPrice ?? '1.5',
+      defaultPriceImpact: mockConfig?.defaultPriceImpact ?? 0.001,
+    }
+
+    // Create mocked functions
+    this.mockExecute = vi
+      .fn()
+      .mockImplementation(this.createMockSwapTransaction.bind(this))
+    this.mockGetPrice = vi
+      .fn()
+      .mockImplementation(this.createMockPrice.bind(this))
+    this.mockGetMarket = vi
+      .fn()
+      .mockImplementation(this.createMockMarket.bind(this))
+    this.mockGetMarkets = vi
+      .fn()
+      .mockImplementation(this.createMockMarkets.bind(this))
+  }
+
+  supportedChainIds(): SupportedChainId[] {
+    return this._supportedChains
+  }
+
+  reset(): void {
+    vi.clearAllMocks()
+  }
+
+  // Expose protected methods for testing
+  public testValidateMarketAllowed(
+    assetIn: any,
+    assetOut: any,
+    chainId: SupportedChainId,
+  ): void {
+    return this.validateMarketAllowed(assetIn, assetOut, chainId)
+  }
+
+  protected async _execute(
+    params: ResolvedSwapParams,
+  ): Promise<SwapTransaction> {
+    return this.mockExecute(params)
+  }
+
+  protected async _getPrice(params: SwapPriceParams): Promise<SwapPrice> {
+    return this.mockGetPrice(params)
+  }
+
+  protected async _getMarket(params: GetSwapMarketParams): Promise<SwapMarket> {
+    return this.mockGetMarket(params)
+  }
+
+  protected async _getMarkets(
+    params: GetSwapMarketsParams,
+  ): Promise<SwapMarket[]> {
+    return this.mockGetMarkets(params)
+  }
+
+  private createMockSwapTransaction(
+    params: ResolvedSwapParams,
+  ): SwapTransaction {
+    const amountIn = params.amountInWei ?? 1000000n
+    const amountOut = 1500000000000000000n
+
+    return {
+      amountIn: 1.0,
+      amountOut: 1.5,
+      amountInWei: amountIn,
+      amountOutWei: amountOut,
+      assetIn: params.assetIn,
+      assetOut: params.assetOut,
+      price: this.mockProviderConfig.defaultPrice,
+      priceImpact: this.mockProviderConfig.defaultPriceImpact,
+      transactionData: {
+        swap: {
+          to: '0x492e6456d9528771018deb9e87ef7750ef184104' as Address,
+          data: '0x1234' as `0x${string}`,
+          value: 0n,
+        },
+      },
+    }
+  }
+
+  private createMockPrice(params: SwapPriceParams): SwapPrice {
+    const amountIn =
+      params.amountIn !== undefined
+        ? BigInt(
+            Math.floor(
+              params.amountIn * 10 ** params.assetIn.metadata.decimals,
+            ),
+          )
+        : BigInt(10 ** params.assetIn.metadata.decimals)
+
+    const amountOut = (amountIn * 15n) / 10n
+
+    return {
+      price: this.mockProviderConfig.defaultPrice,
+      priceInverse: '0.666666',
+      amountIn: 1.0,
+      amountOut: 1.5,
+      amountInWei: amountIn,
+      amountOutWei: amountOut,
+      priceImpact: this.mockProviderConfig.defaultPriceImpact,
+      route: {
+        path: [params.assetIn, params.assetOut!],
+        pools: [
+          {
+            address: '0x1234' as Address,
+            fee: 500,
+            version: 'v4',
+          },
+        ],
+      },
+      gasEstimate: 150000n,
+    }
+  }
+
+  private createMockMarket(params: GetSwapMarketParams): SwapMarket {
+    return {
+      marketId: {
+        poolId: params.poolId,
+        chainId: params.chainId,
+      },
+      assets: [
+        {
+          type: 'erc20',
+          address: { [params.chainId]: '0x1111' as Address },
+          metadata: { name: 'USDC', symbol: 'USDC', decimals: 6 },
+        },
+        {
+          type: 'erc20',
+          address: { [params.chainId]: '0x2222' as Address },
+          metadata: { name: 'WETH', symbol: 'WETH', decimals: 18 },
+        },
+      ],
+      fee: 500,
+      provider: 'uniswap',
+    }
+  }
+
+  private createMockMarkets(_params: GetSwapMarketsParams): SwapMarket[] {
+    return [
+      this.createMockMarket({
+        poolId: '0xpool1',
+        chainId: 84532 as SupportedChainId,
+      }),
+    ]
+  }
+}
+
+/**
+ * Create a mock swap provider
+ */
+export function createMockSwapProvider(
+  config?: SwapProviderConfig,
+  mockConfig?: Partial<MockSwapProviderConfig>,
+): MockSwapProvider {
+  return new MockSwapProvider(config, mockConfig)
+}

package/src/swap/core/SwapProvider.ts

@@ -0,0 +1,319 @@
+import type { Address } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { Asset } from '@/types/asset.js'
+import type {
+  GetSwapMarketParams,
+  GetSwapMarketsParams,
+  ResolvedSwapParams,
+  SwapExecuteParams,
+  SwapMarket,
+  SwapMarketConfig,
+  SwapPrice,
+  SwapPriceParams,
+  SwapProviderConfig,
+  SwapTransaction,
+} from '@/types/swap/index.js'
+import type { TransactionData } from '@/types/transaction.js'
+import {
+  getAssetAddress,
+  isNativeAsset,
+  parseAssetAmount,
+} from '@/utils/assets.js'
+import {
+  buildPermit2ApprovalTx,
+  buildTokenApprovalTx,
+  checkPermit2Allowance,
+  checkTokenAllowance,
+} from '@/utils/permit2.js'
+import {
+  validateAmountPositiveIfExists,
+  validateAmountProvided,
+  validateAssetOnChain,
+  validateChainSupported,
+  validateNotBothAmounts,
+  validateNotSameAsset,
+  validateNotZeroAddress,
+  validateSlippage,
+} from '@/utils/validation.js'
+
+const DEFAULT_SLIPPAGE = 0.005
+const DEFAULT_DEADLINE_OFFSET = 60
+const DEFAULT_MAX_SLIPPAGE = 0.5
+
+/**
+ * Abstract base class for swap providers.
+ * Public methods handle validation and conversion,
+ * protected abstract methods implement provider-specific logic.
+ */
+export abstract class SwapProvider<
+  TConfig extends SwapProviderConfig = SwapProviderConfig,
+> {
+  protected readonly _config: TConfig
+  protected readonly chainManager: ChainManager
+
+  constructor(config: TConfig, chainManager: ChainManager) {
+    this._config = config
+    this.chainManager = chainManager
+  }
+
+  get config(): TConfig {
+    return this._config
+  }
+
+  get defaultSlippage(): number {
+    return this._config.defaultSlippage ?? DEFAULT_SLIPPAGE
+  }
+
+  /**
+   * Execute a token swap
+   * @param params - Swap parameters including assets, amounts, and chain
+   * @returns Swap transaction data ready for execution
+   */
+  async execute(params: SwapExecuteParams): Promise<SwapTransaction> {
+    this.executeValidations(params)
+    const resolvedParams = this.resolveParams(params)
+    validateSlippage(
+      resolvedParams.slippage,
+      this._config.maxSlippage ?? DEFAULT_MAX_SLIPPAGE,
+    )
+    return this._execute(resolvedParams)
+  }
+
+  /** Get price quote for a swap */
+  async getPrice(params: SwapPriceParams): Promise<SwapPrice> {
+    validateChainSupported(params.chainId, this.supportedChainIds())
+    return this._getPrice(params)
+  }
+
+  /** Get a specific swap market by ID */
+  async getMarket(params: GetSwapMarketParams): Promise<SwapMarket> {
+    validateChainSupported(params.chainId, this.supportedChainIds())
+    return this._getMarket(params)
+  }
+
+  /** Get available swap markets, optionally filtered by chainId or asset */
+  async getMarkets(params: GetSwapMarketsParams = {}): Promise<SwapMarket[]> {
+    if (params.chainId) {
+      validateChainSupported(params.chainId, this.supportedChainIds())
+    }
+    return this._getMarkets(params)
+  }
+
+  isChainSupported(chainId: SupportedChainId): boolean {
+    return this.supportedChainIds().includes(chainId)
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Protected helpers
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  protected validateMarketAllowed(
+    assetIn: Asset,
+    assetOut: Asset,
+    chainId: SupportedChainId,
+  ): void {
+    const { marketBlocklist, marketAllowlist } = this._config
+
+    if (marketBlocklist?.length) {
+      const isBlocked = this.findMatchingConfig(
+        assetIn,
+        assetOut,
+        chainId,
+        marketBlocklist,
+      )
+      if (isBlocked) {
+        throw new Error(
+          `Pair ${assetIn.metadata.symbol}/${assetOut.metadata.symbol} is blocked on chain ${chainId}`,
+        )
+      }
+    }
+
+    if (marketAllowlist?.length) {
+      const isAllowed = this.findMatchingConfig(
+        assetIn,
+        assetOut,
+        chainId,
+        marketAllowlist,
+      )
+      if (!isAllowed) {
+        throw new Error(
+          `Pair ${assetIn.metadata.symbol}/${assetOut.metadata.symbol} is not in the allowlist for chain ${chainId}`,
+        )
+      }
+    }
+  }
+
+  protected resolveMarketConfig(
+    assetIn: Asset,
+    assetOut: Asset,
+    chainId: SupportedChainId,
+  ): SwapMarketConfig | undefined {
+    const { marketAllowlist } = this._config
+    if (!marketAllowlist?.length) {
+      throw new Error(
+        'No markets configured. Provide a marketAllowlist in swap provider config.',
+      )
+    }
+    return this.findMatchingConfig(assetIn, assetOut, chainId, marketAllowlist)
+  }
+
+  /**
+   * Build Permit2 approval transactions for an ERC20 swap input.
+   * Skipped for native assets. Checks both ERC20→Permit2 and Permit2→spender allowances in parallel.
+   * @param params - Resolved swap params (wallet address, asset info, chain)
+   * @param requiredAmount - Amount in wei that must be approved
+   * @param permit2Address - Permit2 contract address
+   * @param permit2Spender - The router/contract that Permit2 should approve (e.g. Universal Router)
+   * @param permit2ExpirySeconds - Optional custom expiry for the Permit2 approval
+   */
+  protected async buildPermit2Approvals(
+    params: ResolvedSwapParams,
+    requiredAmount: bigint,
+    permit2Address: Address,
+    permit2Spender: Address,
+    permit2ExpirySeconds?: number,
+  ): Promise<{
+    tokenApproval: TransactionData | undefined
+    permit2Approval: TransactionData | undefined
+  }> {
+    if (isNativeAsset(params.assetIn)) {
+      return { tokenApproval: undefined, permit2Approval: undefined }
+    }
+
+    const publicClient = this.chainManager.getPublicClient(params.chainId)
+    const token = getAssetAddress(params.assetIn, params.chainId)
+
+    const [tokenAllowance, permit2Allowance] = await Promise.all([
+      checkTokenAllowance({
+        publicClient,
+        token,
+        owner: params.walletAddress,
+        spender: permit2Address,
+      }),
+      checkPermit2Allowance({
+        publicClient,
+        permit2Address,
+        owner: params.walletAddress,
+        token,
+        spender: permit2Spender,
+      }),
+    ])
+
+    const tokenApproval =
+      tokenAllowance < requiredAmount
+        ? buildTokenApprovalTx(token, permit2Address)
+        : undefined
+
+    // Permit2 expiration is in Unix seconds (matching EVM block.timestamp)
+    const permit2Expired =
+      permit2Allowance.expiration < Math.floor(Date.now() / 1000)
+    const permit2Approval =
+      permit2Allowance.amount < requiredAmount || permit2Expired
+        ? buildPermit2ApprovalTx({
+            permit2Address,
+            token,
+            spender: permit2Spender,
+            amount: requiredAmount,
+            expirySeconds: permit2ExpirySeconds,
+          })
+        : undefined
+
+    return { tokenApproval, permit2Approval }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Private helpers
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  private executeValidations(params: SwapExecuteParams): void {
+    validateAmountProvided(params.amountIn, params.amountOut)
+    validateAmountPositiveIfExists(params.amountIn)
+    validateAmountPositiveIfExists(params.amountOut)
+    validateNotBothAmounts(params.amountIn, params.amountOut)
+    validateNotSameAsset(params.assetIn, params.assetOut)
+    validateNotZeroAddress(params.walletAddress, 'walletAddress')
+    if (params.recipient) {
+      validateNotZeroAddress(params.recipient, 'recipient')
+    }
+    validateChainSupported(params.chainId, this.supportedChainIds())
+    this.validateMarketAllowed(params.assetIn, params.assetOut, params.chainId)
+    validateAssetOnChain(params.assetIn, params.chainId)
+    validateAssetOnChain(params.assetOut, params.chainId)
+  }
+
+  private resolveParams(params: SwapExecuteParams): ResolvedSwapParams {
+    return {
+      amountInWei: parseAssetAmount(params.assetIn, params.amountIn),
+      amountOutWei: parseAssetAmount(params.assetOut, params.amountOut),
+      assetIn: params.assetIn,
+      assetOut: params.assetOut,
+      slippage: params.slippage ?? this.defaultSlippage,
+      deadline:
+        params.deadline ??
+        Math.floor(Date.now() / 1000) + DEFAULT_DEADLINE_OFFSET,
+      // Send output tokens to specified recipient, or back to the initiating wallet
+      recipient: params.recipient ?? params.walletAddress,
+      walletAddress: params.walletAddress,
+      chainId: params.chainId,
+    }
+  }
+
+  private findMatchingConfig(
+    assetIn: Asset,
+    assetOut: Asset,
+    chainId: SupportedChainId,
+    list: SwapMarketConfig[],
+  ): SwapMarketConfig | undefined {
+    const addressIn = assetIn.address[chainId]
+    const addressOut = assetOut.address[chainId]
+    if (!addressIn || !addressOut) return undefined
+
+    return list.find((config) => {
+      if (config.chainId !== undefined && config.chainId !== chainId)
+        return false
+      return this.containsPairByAddress(
+        addressIn,
+        addressOut,
+        chainId,
+        config.assets,
+      )
+    })
+  }
+
+  private containsPairByAddress(
+    addressIn: string,
+    addressOut: string,
+    chainId: SupportedChainId,
+    assets: Asset[],
+  ): boolean {
+    const addresses = assets
+      .map((a) => a.address[chainId]?.toLowerCase())
+      .filter(Boolean)
+    return (
+      addresses.includes(addressIn.toLowerCase()) &&
+      addresses.includes(addressOut.toLowerCase())
+    )
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Abstract methods (implement in provider)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  abstract supportedChainIds(): SupportedChainId[]
+
+  protected abstract _execute(
+    params: ResolvedSwapParams,
+  ): Promise<SwapTransaction>
+
+  protected abstract _getPrice(params: SwapPriceParams): Promise<SwapPrice>
+
+  protected abstract _getMarket(
+    params: GetSwapMarketParams,
+  ): Promise<SwapMarket>
+
+  protected abstract _getMarkets(
+    params: GetSwapMarketsParams,
+  ): Promise<SwapMarket[]>
+}