@eth-optimism/actions-sdk 0.2.0 → 0.3.0

package/src/swap/core/__tests__/SwapProvider.test.ts

@@ -0,0 +1,478 @@
+import type { Address } from 'viem'
+import { describe, expect, it } from 'vitest'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { MockSwapProvider } from '@/swap/__mocks__/MockSwapProvider.js'
+import type { Asset } from '@/types/asset.js'
+import type { SwapMarketConfig } from '@/types/swap/index.js'
+
+// Test assets
+const MockUSDC: Asset = {
+  type: 'erc20',
+  address: { 84532: '0x1111111111111111111111111111111111111111' as Address },
+  metadata: { name: 'USD Coin', symbol: 'USDC', decimals: 6 },
+}
+
+const MockWETH: Asset = {
+  type: 'erc20',
+  address: { 84532: '0x2222222222222222222222222222222222222222' as Address },
+  metadata: { name: 'Wrapped Ether', symbol: 'WETH', decimals: 18 },
+}
+
+const MockOP: Asset = {
+  type: 'erc20',
+  address: { 84532: '0x3333333333333333333333333333333333333333' as Address },
+  metadata: { name: 'Optimism', symbol: 'OP', decimals: 18 },
+}
+
+describe('SwapProvider', () => {
+  describe('constructor and configuration', () => {
+    it('should initialize with default config', () => {
+      const provider = new MockSwapProvider()
+      expect(provider).toBeDefined()
+      expect(provider.supportedChainIds()).toContain(84532)
+    })
+
+    it('should use default slippage when not configured', () => {
+      const provider = new MockSwapProvider()
+      expect(provider.defaultSlippage).toBe(0.005)
+    })
+
+    it('should use config slippage when provided', () => {
+      const provider = new MockSwapProvider({ defaultSlippage: 0.01 })
+      expect(provider.defaultSlippage).toBe(0.01)
+    })
+
+    it('should store market allowlist when provided', () => {
+      const config: SwapMarketConfig = {
+        assets: [MockUSDC, MockWETH],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({ marketAllowlist: [config] })
+      expect(provider.config.marketAllowlist).toEqual([config])
+    })
+  })
+
+  describe('execute()', () => {
+    it('should throw if neither amountIn nor amountOut provided', async () => {
+      const provider = new MockSwapProvider()
+      await expect(
+        provider.execute({
+          assetIn: MockUSDC,
+          assetOut: MockWETH,
+          chainId: 84532 as SupportedChainId,
+          walletAddress: '0x1234' as Address,
+        }),
+      ).rejects.toThrow('Either amountIn or amountOut must be provided')
+    })
+
+    it('should throw if chain not supported', async () => {
+      const provider = new MockSwapProvider()
+      await expect(
+        provider.execute({
+          amountIn: 100,
+          assetIn: MockUSDC,
+          assetOut: MockWETH,
+          chainId: 999 as SupportedChainId,
+          walletAddress: '0x1234' as Address,
+        }),
+      ).rejects.toThrow('Chain 999 is not supported')
+    })
+
+    it('should throw if asset not supported on chain', async () => {
+      const unsupportedAsset: Asset = {
+        type: 'erc20',
+        address: { 1: '0x1111' as Address }, // Only on mainnet
+        metadata: { name: 'Test', symbol: 'TEST', decimals: 18 },
+      }
+      const provider = new MockSwapProvider()
+      await expect(
+        provider.execute({
+          amountIn: 100,
+          assetIn: unsupportedAsset,
+          assetOut: MockWETH,
+          chainId: 84532 as SupportedChainId,
+          walletAddress: '0x1234' as Address,
+        }),
+      ).rejects.toThrow('not supported on chain')
+    })
+
+    it('should use param slippage over config default', async () => {
+      const provider = new MockSwapProvider({ defaultSlippage: 0.01 })
+      const result = await provider.execute({
+        amountIn: 100,
+        assetIn: MockUSDC,
+        assetOut: MockWETH,
+        chainId: 84532 as SupportedChainId,
+        walletAddress: '0x1234' as Address,
+        slippage: 0.02,
+      })
+      expect(result).toBeDefined()
+      // Slippage is passed to internal params
+      expect(provider.mockExecute).toHaveBeenCalledWith(
+        expect.objectContaining({ slippage: 0.02 }),
+      )
+    })
+
+    it('should use default deadline when not specified', async () => {
+      const provider = new MockSwapProvider()
+      const beforeTime = Math.floor(Date.now() / 1000)
+      await provider.execute({
+        amountIn: 100,
+        assetIn: MockUSDC,
+        assetOut: MockWETH,
+        chainId: 84532 as SupportedChainId,
+        walletAddress: '0x1234' as Address,
+      })
+      const afterTime = Math.floor(Date.now() / 1000) + 60
+
+      expect(provider.mockExecute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          deadline: expect.any(Number),
+        }),
+      )
+      const call = provider.mockExecute.mock.calls[0][0]
+      expect(call.deadline).toBeGreaterThanOrEqual(beforeTime + 60)
+      expect(call.deadline).toBeLessThanOrEqual(afterTime)
+    })
+
+    it('should convert human-readable amounts to wei', async () => {
+      const provider = new MockSwapProvider()
+      await provider.execute({
+        amountIn: 100,
+        assetIn: MockUSDC, // 6 decimals
+        assetOut: MockWETH,
+        chainId: 84532 as SupportedChainId,
+        walletAddress: '0x1234' as Address,
+      })
+
+      expect(provider.mockExecute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          amountInWei: 100000000n, // 100 * 10^6
+        }),
+      )
+    })
+
+    it('should return swap transaction', async () => {
+      const provider = new MockSwapProvider()
+      const result = await provider.execute({
+        amountIn: 100,
+        assetIn: MockUSDC,
+        assetOut: MockWETH,
+        chainId: 84532 as SupportedChainId,
+        walletAddress: '0x1234' as Address,
+      })
+
+      expect(result.amountIn).toBeDefined()
+      expect(result.amountOut).toBeDefined()
+      expect(result.transactionData.swap).toBeDefined()
+    })
+  })
+
+  describe('getPrice()', () => {
+    it('should throw if chain not supported', async () => {
+      const provider = new MockSwapProvider()
+      await expect(
+        provider.getPrice({
+          assetIn: MockUSDC,
+          assetOut: MockWETH,
+          chainId: 999 as SupportedChainId,
+        }),
+      ).rejects.toThrow('Chain 999 is not supported')
+    })
+
+    it('should return price quote', async () => {
+      const provider = new MockSwapProvider()
+      const price = await provider.getPrice({
+        assetIn: MockUSDC,
+        assetOut: MockWETH,
+        amountIn: 100,
+        chainId: 84532 as SupportedChainId,
+      })
+
+      expect(price.price).toBeDefined()
+      expect(price.amountIn).toBeDefined()
+      expect(price.amountOut).toBeDefined()
+      expect(price.route).toBeDefined()
+    })
+  })
+
+  describe('getMarket()', () => {
+    it('should throw if chain not supported', async () => {
+      const provider = new MockSwapProvider()
+      await expect(
+        provider.getMarket({
+          poolId: '0xpool1',
+          chainId: 999 as SupportedChainId,
+        }),
+      ).rejects.toThrow('Chain 999 is not supported')
+    })
+
+    it('should return market info', async () => {
+      const provider = new MockSwapProvider()
+      const market = await provider.getMarket({
+        poolId: '0xpool1',
+        chainId: 84532 as SupportedChainId,
+      })
+
+      expect(market.marketId.poolId).toBe('0xpool1')
+      expect(market.assets).toHaveLength(2)
+      expect(market.provider).toBe('uniswap')
+    })
+  })
+
+  describe('getMarkets()', () => {
+    it('should return markets array', async () => {
+      const provider = new MockSwapProvider()
+      const markets = await provider.getMarkets()
+
+      expect(Array.isArray(markets)).toBe(true)
+      expect(markets.length).toBeGreaterThan(0)
+    })
+
+    it('should validate chainId if provided', async () => {
+      const provider = new MockSwapProvider()
+      await expect(
+        provider.getMarkets({ chainId: 999 as SupportedChainId }),
+      ).rejects.toThrow('Chain 999 is not supported')
+    })
+  })
+
+  describe('supportedChainIds()', () => {
+    it('should return array of supported chain IDs', () => {
+      const provider = new MockSwapProvider()
+      const chainIds = provider.supportedChainIds()
+
+      expect(Array.isArray(chainIds)).toBe(true)
+      expect(chainIds).toContain(84532)
+    })
+  })
+
+  describe('isChainSupported()', () => {
+    it('should return true for supported chain', () => {
+      const provider = new MockSwapProvider()
+      expect(provider.isChainSupported(84532 as SupportedChainId)).toBe(true)
+    })
+
+    it('should return false for unsupported chain', () => {
+      const provider = new MockSwapProvider()
+      expect(provider.isChainSupported(999 as SupportedChainId)).toBe(false)
+    })
+  })
+
+  describe('validateMarketAllowed()', () => {
+    it('should allow any pair when no allowlist configured', () => {
+      const provider = new MockSwapProvider()
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockUSDC,
+          MockWETH,
+          84532 as SupportedChainId,
+        ),
+      ).not.toThrow()
+    })
+
+    it('should allow pairs in allowlist', () => {
+      const config: SwapMarketConfig = {
+        assets: [MockUSDC, MockWETH],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({ marketAllowlist: [config] })
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockUSDC,
+          MockWETH,
+          84532 as SupportedChainId,
+        ),
+      ).not.toThrow()
+    })
+
+    it('should reject pairs not in allowlist', () => {
+      const config: SwapMarketConfig = {
+        assets: [MockUSDC, MockWETH],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({ marketAllowlist: [config] })
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockUSDC,
+          MockOP,
+          84532 as SupportedChainId,
+        ),
+      ).toThrow('not in the allowlist')
+    })
+
+    it('should match pairs regardless of order', () => {
+      const config: SwapMarketConfig = {
+        assets: [MockUSDC, MockWETH],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({ marketAllowlist: [config] })
+      // Reversed order should still match
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockWETH,
+          MockUSDC,
+          84532 as SupportedChainId,
+        ),
+      ).not.toThrow()
+    })
+
+    it('should reject blocklisted pairs', () => {
+      const config: SwapMarketConfig = {
+        assets: [MockUSDC, MockOP],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({ marketBlocklist: [config] })
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockUSDC,
+          MockOP,
+          84532 as SupportedChainId,
+        ),
+      ).toThrow('is blocked')
+    })
+
+    it('should check blocklist before allowlist', () => {
+      const allowConfig: SwapMarketConfig = {
+        assets: [MockUSDC, MockWETH],
+        chainId: 84532 as SupportedChainId,
+      }
+      const blockConfig: SwapMarketConfig = {
+        assets: [MockUSDC, MockWETH],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({
+        marketAllowlist: [allowConfig],
+        marketBlocklist: [blockConfig],
+      })
+      // Blocklist takes precedence
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockUSDC,
+          MockWETH,
+          84532 as SupportedChainId,
+        ),
+      ).toThrow('is blocked')
+    })
+
+    it('should expand multi-asset filter to all pairs', () => {
+      const config: SwapMarketConfig = {
+        assets: [MockUSDC, MockWETH, MockOP],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({ marketAllowlist: [config] })
+
+      // All 3 pairs should be allowed: USDC/WETH, USDC/OP, WETH/OP
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockUSDC,
+          MockWETH,
+          84532 as SupportedChainId,
+        ),
+      ).not.toThrow()
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockUSDC,
+          MockOP,
+          84532 as SupportedChainId,
+        ),
+      ).not.toThrow()
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          MockWETH,
+          MockOP,
+          84532 as SupportedChainId,
+        ),
+      ).not.toThrow()
+    })
+
+    it('should match any chain when filter has no chainId', () => {
+      // Assets with addresses on both chains
+      const multiChainUSDC: Asset = {
+        ...MockUSDC,
+        address: {
+          84532: '0x1111111111111111111111111111111111111111' as Address,
+          10: '0x1111111111111111111111111111111111111112' as Address,
+        },
+      }
+      const multiChainWETH: Asset = {
+        ...MockWETH,
+        address: {
+          84532: '0x2222222222222222222222222222222222222222' as Address,
+          10: '0x2222222222222222222222222222222222222223' as Address,
+        },
+      }
+      const config: SwapMarketConfig = {
+        assets: [multiChainUSDC, multiChainWETH],
+      }
+      const provider = new MockSwapProvider(
+        { marketAllowlist: [config] },
+        {
+          supportedChains: [84532 as SupportedChainId, 10 as SupportedChainId],
+        },
+      )
+
+      // Should match on any supported chain
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          multiChainUSDC,
+          multiChainWETH,
+          84532 as SupportedChainId,
+        ),
+      ).not.toThrow()
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          multiChainUSDC,
+          multiChainWETH,
+          10 as SupportedChainId,
+        ),
+      ).not.toThrow()
+    })
+
+    it('should scope filter to specific chainId when provided', () => {
+      const multiChainUSDC: Asset = {
+        ...MockUSDC,
+        address: {
+          84532: '0x1111111111111111111111111111111111111111' as Address,
+          10: '0x1111111111111111111111111111111111111112' as Address,
+        },
+      }
+      const multiChainWETH: Asset = {
+        ...MockWETH,
+        address: {
+          84532: '0x2222222222222222222222222222222222222222' as Address,
+          10: '0x2222222222222222222222222222222222222223' as Address,
+        },
+      }
+      const config: SwapMarketConfig = {
+        assets: [multiChainUSDC, multiChainWETH],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider(
+        { marketAllowlist: [config] },
+        {
+          supportedChains: [84532 as SupportedChainId, 10 as SupportedChainId],
+        },
+      )
+
+      // Should match on 84532
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          multiChainUSDC,
+          multiChainWETH,
+          84532 as SupportedChainId,
+        ),
+      ).not.toThrow()
+
+      // Should NOT match on chain 10
+      expect(() =>
+        provider.testValidateMarketAllowed(
+          multiChainUSDC,
+          multiChainWETH,
+          10 as SupportedChainId,
+        ),
+      ).toThrow('not in the allowlist')
+    })
+  })
+})

package/src/swap/index.ts

@@ -0,0 +1,14 @@
+// Core
+export { SwapProvider } from '@/swap/core/SwapProvider.js'
+
+// Namespaces
+export { ActionsSwapNamespace } from '@/swap/namespaces/ActionsSwapNamespace.js'
+export { BaseSwapNamespace } from '@/swap/namespaces/BaseSwapNamespace.js'
+export { WalletSwapNamespace } from '@/swap/namespaces/WalletSwapNamespace.js'
+
+// Providers
+export type {
+  UniswapMarketConfig,
+  UniswapSwapProviderConfig,
+} from '@/swap/providers/uniswap/types.js'
+export { UniswapSwapProvider } from '@/swap/providers/uniswap/UniswapSwapProvider.js'

package/src/swap/namespaces/ActionsSwapNamespace.ts

@@ -0,0 +1,7 @@
+import { BaseSwapNamespace } from '@/swap/namespaces/BaseSwapNamespace.js'
+
+/**
+ * Actions swap namespace (read-only, no wallet required)
+ * @description Provides price(), getMarket(), and getMarkets() for read-only access without a wallet
+ */
+export class ActionsSwapNamespace extends BaseSwapNamespace {}

package/src/swap/namespaces/BaseSwapNamespace.ts

@@ -0,0 +1,77 @@
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { SwapProvider } from '@/swap/core/SwapProvider.js'
+import type {
+  GetSwapMarketParams,
+  GetSwapMarketsParams,
+  SwapMarket,
+  SwapPrice,
+  SwapPriceParams,
+  SwapProviderConfig,
+  SwapProviders,
+} from '@/types/swap/index.js'
+
+/**
+ * Base swap namespace with shared read-only operations
+ */
+export abstract class BaseSwapNamespace {
+  constructor(protected readonly providers: SwapProviders) {}
+
+  /**
+   * Get price quote for a swap
+   */
+  async price(params: SwapPriceParams): Promise<SwapPrice> {
+    const provider = this.getProvider()
+    return provider.getPrice(params)
+  }
+
+  /**
+   * Get a specific swap market
+   * @param params - Market identifier
+   * @returns Market information
+   */
+  async getMarket(params: GetSwapMarketParams): Promise<SwapMarket> {
+    const provider = this.getProvider()
+    return provider.getMarket(params)
+  }
+
+  /**
+   * Get available swap markets across all providers
+   * @param params - Optional filtering by chainId or asset
+   * @returns Promise resolving to array of markets from all providers
+   */
+  async getMarkets(params: GetSwapMarketsParams = {}): Promise<SwapMarket[]> {
+    const results = await Promise.all(
+      this.getAllProviders().map((p) => p.getMarkets(params)),
+    )
+    return results.flat()
+  }
+
+  /**
+   * Get all supported chain IDs across all providers
+   */
+  supportedChainIds(): SupportedChainId[] {
+    const chainIds = new Set<SupportedChainId>()
+    for (const provider of this.getAllProviders()) {
+      for (const chainId of provider.supportedChainIds()) {
+        chainIds.add(chainId)
+      }
+    }
+    return Array.from(chainIds)
+  }
+
+  // SwapProviders keys are optional (uniswap?, aerodrome?, etc.) so filter out unconfigured ones
+  protected getAllProviders(): Array<SwapProvider<SwapProviderConfig>> {
+    return Object.values(this.providers).filter(
+      (p): p is SwapProvider<SwapProviderConfig> => p !== undefined,
+    )
+  }
+
+  // Future: resolve the best provider for given params (e.g. best price across Uniswap, Aerodrome, etc.)
+  protected getProvider(): SwapProvider<SwapProviderConfig> {
+    const provider = this.providers.uniswap
+    if (!provider) {
+      throw new Error('No swap provider configured')
+    }
+    return provider
+  }
+}

package/src/swap/namespaces/WalletSwapNamespace.ts

@@ -0,0 +1,82 @@
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { BaseSwapNamespace } from '@/swap/namespaces/BaseSwapNamespace.js'
+import type {
+  SwapProviders,
+  SwapReceipt,
+  SwapTransaction,
+  WalletSwapParams,
+} from '@/types/swap/index.js'
+import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+
+/**
+ * Wallet swap namespace (full operations with signing)
+ * @description Provides execute() for swapping tokens
+ */
+export class WalletSwapNamespace extends BaseSwapNamespace {
+  constructor(
+    providers: SwapProviders,
+    private readonly wallet: Wallet,
+  ) {
+    super(providers)
+  }
+
+  /**
+   * Execute a token swap
+   * @param params - Swap parameters including chainId
+   * @returns Swap receipt with transaction details
+   */
+  async execute(params: WalletSwapParams): Promise<SwapReceipt> {
+    const provider = this.getProvider()
+
+    // Build swap transaction
+    const swapTx = await provider.execute({
+      ...params,
+      walletAddress: this.wallet.address,
+    })
+
+    // Execute transaction(s)
+    const receipt = await this.executeTransaction(swapTx, params.chainId)
+
+    return {
+      receipt,
+      amountIn: swapTx.amountIn,
+      amountOut: swapTx.amountOut,
+      amountInWei: swapTx.amountInWei,
+      amountOutWei: swapTx.amountOutWei,
+      assetIn: swapTx.assetIn,
+      assetOut: swapTx.assetOut,
+      price: swapTx.price,
+      priceImpact: swapTx.priceImpact,
+    }
+  }
+
+  /**
+   * Execute swap transaction with approval batching
+   */
+  private async executeTransaction(
+    swapTx: SwapTransaction,
+    chainId: SupportedChainId,
+  ): Promise<SwapReceipt['receipt']> {
+    const { transactionData } = swapTx
+    const txs = []
+
+    // Add token approval if needed
+    if (transactionData.tokenApproval) {
+      txs.push(transactionData.tokenApproval)
+    }
+
+    // Add Permit2 approval if needed
+    if (transactionData.permit2Approval) {
+      txs.push(transactionData.permit2Approval)
+    }
+
+    // Add main swap transaction
+    txs.push(transactionData.swap)
+
+    // Execute as batch if multiple transactions, otherwise single
+    if (txs.length > 1) {
+      return this.wallet.sendBatch(txs, chainId)
+    }
+    return this.wallet.send(transactionData.swap, chainId)
+  }
+}