@eth-optimism/actions-sdk 0.3.0 → 0.4.0

package/src/swap/providers/velodrome/__tests__/encoding.v2.test.ts

@@ -0,0 +1,235 @@
+import type { Address } from 'viem'
+import { describe, expect, it } from 'vitest'
+
+import {
+  MockETHAsset,
+  MockUSDCAsset,
+  MockWETHAsset,
+} from '@/__mocks__/MockAssets.js'
+import {
+  LEAF_ROUTER_ABI,
+  UNIVERSAL_ROUTER_ABI,
+  V2_ROUTER_ABI,
+} from '@/swap/providers/velodrome/abis.js'
+import { encodeSwap } from '@/swap/providers/velodrome/encoding/index.js'
+
+import {
+  BASE_CHAIN_ID,
+  DEADLINE,
+  decode,
+  FACTORY,
+  OP_CHAIN_ID,
+  RECIPIENT,
+} from './encoding.helpers.js'
+
+describe('encodeSwap', () => {
+  describe('v2 router', () => {
+    it('encodes swapExactTokensForTokens with 4-field Route', () => {
+      const data = encodeSwap({
+        assetIn: MockUSDCAsset,
+        assetOut: MockWETHAsset,
+        amountInRaw: 1000000n,
+        amountOutMin: 400000000000000000n,
+        routerType: 'v2',
+        stable: false,
+        factoryAddress: FACTORY,
+        recipient: RECIPIENT,
+        deadline: DEADLINE,
+        chainId: OP_CHAIN_ID,
+      })
+
+      type V2Route = {
+        from: Address
+        to: Address
+        stable: boolean
+        factory: Address
+      }
+      const { functionName, args } = decode<
+        [bigint, bigint, V2Route[], Address, bigint]
+      >(V2_ROUTER_ABI, data)
+      expect(functionName).toBe('swapExactTokensForTokens')
+      expect(args[0]).toBe(1000000n)
+      expect(args[1]).toBe(400000000000000000n)
+      expect(args[2]).toHaveLength(1)
+      expect(args[2][0].factory).toBe(FACTORY)
+      expect(args[2][0].stable).toBe(false)
+      expect(args[3]).toBe(RECIPIENT)
+    })
+
+    it('encodes swapExactETHForTokens for native input', () => {
+      const data = encodeSwap({
+        assetIn: MockETHAsset,
+        assetOut: MockUSDCAsset,
+        amountInRaw: 1000000000000000000n,
+        amountOutMin: 900000n,
+        routerType: 'v2',
+        stable: false,
+        factoryAddress: FACTORY,
+        recipient: RECIPIENT,
+        deadline: DEADLINE,
+        chainId: OP_CHAIN_ID,
+      })
+
+      type V2Route = {
+        from: Address
+        to: Address
+        stable: boolean
+        factory: Address
+      }
+      const { functionName, args } = decode<
+        [bigint, V2Route[], Address, bigint]
+      >(V2_ROUTER_ABI, data)
+      expect(functionName).toBe('swapExactETHForTokens')
+      expect(args[0]).toBe(900000n)
+      expect(args[1]).toHaveLength(1)
+      expect(args[1][0].from).toBe('0x4200000000000000000000000000000000000006')
+    })
+
+    it('encodes swapExactTokensForETH for native output', () => {
+      const data = encodeSwap({
+        assetIn: MockUSDCAsset,
+        assetOut: MockETHAsset,
+        amountInRaw: 1000000n,
+        amountOutMin: 400000000000000000n,
+        routerType: 'v2',
+        stable: false,
+        factoryAddress: FACTORY,
+        recipient: RECIPIENT,
+        deadline: DEADLINE,
+        chainId: OP_CHAIN_ID,
+      })
+
+      const { functionName } = decode(V2_ROUTER_ABI, data)
+      expect(functionName).toBe('swapExactTokensForETH')
+    })
+  })
+
+  describe('leaf router', () => {
+    it('encodes swapExactTokensForTokens with 3-field Route (no factory)', () => {
+      const data = encodeSwap({
+        assetIn: MockUSDCAsset,
+        assetOut: MockWETHAsset,
+        amountInRaw: 1000000n,
+        amountOutMin: 400000000000000000n,
+        routerType: 'leaf',
+        stable: false,
+        factoryAddress: FACTORY,
+        recipient: RECIPIENT,
+        deadline: DEADLINE,
+        chainId: OP_CHAIN_ID,
+      })
+
+      type LeafRoute = { from: Address; to: Address; stable: boolean }
+      const { functionName, args } = decode<
+        [bigint, bigint, LeafRoute[], Address, bigint]
+      >(LEAF_ROUTER_ABI, data)
+      expect(functionName).toBe('swapExactTokensForTokens')
+      expect(args[0]).toBe(1000000n)
+      expect(args[1]).toBe(400000000000000000n)
+      expect(args[2]).toHaveLength(1)
+      expect(args[2][0].stable).toBe(false)
+      expect((args[2][0] as Record<string, unknown>).factory).toBeUndefined()
+    })
+
+    it('encodes swapExactETHForTokens for native input', () => {
+      const data = encodeSwap({
+        assetIn: MockETHAsset,
+        assetOut: MockUSDCAsset,
+        amountInRaw: 1000000000000000000n,
+        amountOutMin: 900000n,
+        routerType: 'leaf',
+        stable: false,
+        factoryAddress: FACTORY,
+        recipient: RECIPIENT,
+        deadline: DEADLINE,
+        chainId: OP_CHAIN_ID,
+      })
+
+      const { functionName } = decode(LEAF_ROUTER_ABI, data)
+      expect(functionName).toBe('swapExactETHForTokens')
+    })
+
+    it('encodes stable pool swap', () => {
+      const data = encodeSwap({
+        assetIn: MockUSDCAsset,
+        assetOut: MockWETHAsset,
+        amountInRaw: 1000000n,
+        amountOutMin: 400000000000000000n,
+        routerType: 'leaf',
+        stable: true,
+        factoryAddress: FACTORY,
+        recipient: RECIPIENT,
+        deadline: DEADLINE,
+        chainId: OP_CHAIN_ID,
+      })
+
+      type LeafRoute = { from: Address; to: Address; stable: boolean }
+      const { args } = decode<[bigint, bigint, LeafRoute[]]>(
+        LEAF_ROUTER_ABI,
+        data,
+      )
+      expect(args[2][0].stable).toBe(true)
+    })
+  })
+
+  describe('universal router', () => {
+    it('encodes execute() with V2_SWAP_EXACT_IN command', () => {
+      const data = encodeSwap({
+        assetIn: MockUSDCAsset,
+        assetOut: MockWETHAsset,
+        amountInRaw: 1000000n,
+        amountOutMin: 400000000000000000n,
+        routerType: 'universal',
+        stable: false,
+        factoryAddress: FACTORY,
+        recipient: RECIPIENT,
+        deadline: DEADLINE,
+        chainId: BASE_CHAIN_ID,
+      })
+
+      const { functionName, args } = decode<[string, string[], bigint]>(
+        UNIVERSAL_ROUTER_ABI,
+        data,
+      )
+      expect(functionName).toBe('execute')
+      const [commands, inputs, deadline] = args
+      expect(commands).toBe('0x08')
+      expect(inputs).toHaveLength(1)
+      expect(deadline).toBe(BigInt(DEADLINE))
+    })
+  })
+
+  describe('router type comparison', () => {
+    const baseParams = {
+      assetIn: MockUSDCAsset,
+      assetOut: MockWETHAsset,
+      amountInRaw: 1000000n,
+      amountOutMin: 400000000000000000n,
+      stable: false,
+      factoryAddress: FACTORY,
+      recipient: RECIPIENT,
+      deadline: DEADLINE,
+      chainId: OP_CHAIN_ID,
+    } as const
+
+    it('produces different calldata per router type', () => {
+      const universalData = encodeSwap({
+        ...baseParams,
+        routerType: 'universal',
+      })
+      const v2Data = encodeSwap({ ...baseParams, routerType: 'v2' })
+      const leafData = encodeSwap({ ...baseParams, routerType: 'leaf' })
+
+      expect(universalData).not.toBe(v2Data)
+      expect(v2Data).not.toBe(leafData)
+      expect(universalData).not.toBe(leafData)
+    })
+
+    it('v2 calldata is longer than leaf (factory field)', () => {
+      const v2Data = encodeSwap({ ...baseParams, routerType: 'v2' })
+      const leafData = encodeSwap({ ...baseParams, routerType: 'leaf' })
+
+      expect(v2Data.length).toBeGreaterThan(leafData.length)
+    })
+  })
+})

package/src/swap/providers/velodrome/abis.ts

@@ -0,0 +1,264 @@
+/**
+ * Route struct components for v2 routers (Optimism, Base).
+ * Includes factory address for multi-factory support.
+ */
+const V2_ROUTE_COMPONENTS = [
+  { name: 'from', type: 'address' },
+  { name: 'to', type: 'address' },
+  { name: 'stable', type: 'bool' },
+  { name: 'factory', type: 'address' },
+] as const
+
+/**
+ * Route struct components for leaf routers (Relay chains).
+ * Omits factory — leaf routers use a single default factory.
+ */
+const LEAF_ROUTE_COMPONENTS = [
+  { name: 'from', type: 'address' },
+  { name: 'to', type: 'address' },
+  { name: 'stable', type: 'bool' },
+] as const
+
+/**
+ * Velodrome/Aerodrome v2 Router ABI (hub chains: Optimism, Base)
+ * @see https://github.com/velodrome-finance/contracts/blob/main/contracts/Router.sol
+ */
+export const V2_ROUTER_ABI = [
+  {
+    name: 'swapExactTokensForTokens',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'amountIn', type: 'uint256' },
+      { name: 'amountOutMin', type: 'uint256' },
+      {
+        name: 'routes',
+        type: 'tuple[]',
+        components: [...V2_ROUTE_COMPONENTS],
+      },
+      { name: 'to', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+    ],
+    outputs: [{ name: 'amounts', type: 'uint256[]' }],
+  },
+  {
+    name: 'swapExactETHForTokens',
+    type: 'function',
+    stateMutability: 'payable',
+    inputs: [
+      { name: 'amountOutMin', type: 'uint256' },
+      {
+        name: 'routes',
+        type: 'tuple[]',
+        components: [...V2_ROUTE_COMPONENTS],
+      },
+      { name: 'to', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+    ],
+    outputs: [{ name: 'amounts', type: 'uint256[]' }],
+  },
+  {
+    name: 'swapExactTokensForETH',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'amountIn', type: 'uint256' },
+      { name: 'amountOutMin', type: 'uint256' },
+      {
+        name: 'routes',
+        type: 'tuple[]',
+        components: [...V2_ROUTE_COMPONENTS],
+      },
+      { name: 'to', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+    ],
+    outputs: [{ name: 'amounts', type: 'uint256[]' }],
+  },
+  {
+    name: 'getAmountsOut',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'amountIn', type: 'uint256' },
+      {
+        name: 'routes',
+        type: 'tuple[]',
+        components: [...V2_ROUTE_COMPONENTS],
+      },
+    ],
+    outputs: [{ name: 'amounts', type: 'uint256[]' }],
+  },
+] as const
+
+/**
+ * Velodrome/Aerodrome leaf Router ABI (Relay leaf chains)
+ * @see https://github.com/velodrome-finance/superchain-contracts
+ */
+export const LEAF_ROUTER_ABI = [
+  {
+    name: 'swapExactTokensForTokens',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'amountIn', type: 'uint256' },
+      { name: 'amountOutMin', type: 'uint256' },
+      {
+        name: 'routes',
+        type: 'tuple[]',
+        components: [...LEAF_ROUTE_COMPONENTS],
+      },
+      { name: 'to', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+    ],
+    outputs: [{ name: 'amounts', type: 'uint256[]' }],
+  },
+  {
+    name: 'swapExactETHForTokens',
+    type: 'function',
+    stateMutability: 'payable',
+    inputs: [
+      { name: 'amountOutMin', type: 'uint256' },
+      {
+        name: 'routes',
+        type: 'tuple[]',
+        components: [...LEAF_ROUTE_COMPONENTS],
+      },
+      { name: 'to', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+    ],
+    outputs: [{ name: 'amounts', type: 'uint256[]' }],
+  },
+  {
+    name: 'swapExactTokensForETH',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'amountIn', type: 'uint256' },
+      { name: 'amountOutMin', type: 'uint256' },
+      {
+        name: 'routes',
+        type: 'tuple[]',
+        components: [...LEAF_ROUTE_COMPONENTS],
+      },
+      { name: 'to', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+    ],
+    outputs: [{ name: 'amounts', type: 'uint256[]' }],
+  },
+  {
+    name: 'getAmountsOut',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'amountIn', type: 'uint256' },
+      {
+        name: 'routes',
+        type: 'tuple[]',
+        components: [...LEAF_ROUTE_COMPONENTS],
+      },
+    ],
+    outputs: [{ name: 'amounts', type: 'uint256[]' }],
+  },
+] as const
+
+/**
+ * Velodrome/Aerodrome Universal Router ABI
+ * Uses a command-based execute() pattern for all swap operations.
+ */
+export const UNIVERSAL_ROUTER_ABI = [
+  {
+    name: 'execute',
+    type: 'function',
+    stateMutability: 'payable',
+    inputs: [
+      { name: 'commands', type: 'bytes' },
+      { name: 'inputs', type: 'bytes[]' },
+      { name: 'deadline', type: 'uint256' },
+    ],
+    outputs: [],
+  },
+] as const
+
+/**
+ * Velodrome/Aerodrome Pool ABI for direct quoting.
+ * Used when the Universal Router is the only router available (no legacy getAmountsOut).
+ */
+export const POOL_ABI = [
+  {
+    name: 'getAmountOut',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'amountIn', type: 'uint256' },
+      { name: 'tokenIn', type: 'address' },
+    ],
+    outputs: [{ type: 'uint256' }],
+  },
+] as const
+
+/**
+ * Velodrome/Aerodrome PoolFactory ABI for looking up pools.
+ */
+export const POOL_FACTORY_ABI = [
+  {
+    name: 'getPool',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'tokenA', type: 'address' },
+      { name: 'tokenB', type: 'address' },
+      { name: 'stable', type: 'bool' },
+    ],
+    outputs: [{ type: 'address' }],
+  },
+] as const
+
+/**
+ * CL/Slipstream PoolFactory ABI for looking up CL pools.
+ * Uses int24 tickSpacing instead of bool stable.
+ */
+export const CL_POOL_FACTORY_ABI = [
+  {
+    name: 'getPool',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'tokenA', type: 'address' },
+      { name: 'tokenB', type: 'address' },
+      { name: 'tickSpacing', type: 'int24' },
+    ],
+    outputs: [{ type: 'address' }],
+  },
+] as const
+
+/**
+ * CL/Slipstream QuoterV2 ABI for simulating swaps off-chain.
+ * quoteExactInputSingle returns the expected output for a given exact input.
+ * @see https://github.com/velodrome-finance/slipstream
+ */
+export const CL_QUOTER_ABI = [
+  {
+    name: 'quoteExactInputSingle',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      {
+        name: 'params',
+        type: 'tuple',
+        components: [
+          { name: 'tokenIn', type: 'address' },
+          { name: 'tokenOut', type: 'address' },
+          { name: 'amountIn', type: 'uint256' },
+          { name: 'tickSpacing', type: 'int24' },
+          { name: 'sqrtPriceLimitX96', type: 'uint160' },
+        ],
+      },
+    ],
+    outputs: [
+      { name: 'amountOut', type: 'uint256' },
+      { name: 'sqrtPriceX96After', type: 'uint160' },
+      { name: 'initializedTicksCrossed', type: 'uint32' },
+      { name: 'gasEstimate', type: 'uint256' },
+    ],
+  },
+] as const

package/src/swap/providers/velodrome/addresses.ts

@@ -0,0 +1,107 @@
+import type { Address } from 'viem'
+import {
+  base,
+  baseSepolia,
+  bob,
+  celo,
+  fraxtal,
+  ink,
+  lisk,
+  metalL2,
+  mode,
+  optimism,
+  soneium,
+  superseed,
+  unichain,
+} from 'viem/chains'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+
+/** Router contract variant: v2 (legacy), leaf (relay chains), universal (new) */
+export type VelodromeRouterType = 'v2' | 'leaf' | 'universal'
+
+/**
+ * Contract addresses deployed on a single chain.
+ * Keys match official Velodrome/Aerodrome contract names.
+ */
+export interface VelodromeContracts {
+  /** Router — swaps and liquidity operations */
+  router: Address
+  /** PoolFactory — creates v2 AMM pools (volatile/stable) */
+  poolFactory: Address
+  /** CL/Slipstream PoolFactory — creates concentrated liquidity pools */
+  clPoolFactory?: Address
+  /** CL/Slipstream QuoterV2 — off-chain swap simulation for CL pools */
+  clQuoterV2?: Address
+}
+
+/**
+ * Per-chain Velodrome/Aerodrome configuration.
+ * Structured as { contracts, metadata } for clean separation of
+ * validated addresses from provider-specific configuration.
+ */
+export interface VelodromeChainConfig {
+  contracts: VelodromeContracts
+  metadata: {
+    routerType: VelodromeRouterType
+  }
+}
+
+/** Shared config for all Velodrome Relay leaf chains (identical contracts). */
+const LEAF_CHAIN_CONFIG: VelodromeChainConfig = {
+  contracts: {
+    router: '0x3a63171DD9BebF4D07BC782FECC7eb0b890C2A45',
+    poolFactory: '0x31832f2a97Fd20664D76Cc421207669b55CE4BC0',
+  },
+  metadata: { routerType: 'leaf' },
+}
+
+/**
+ * Velodrome/Aerodrome chain configurations.
+ *
+ * Hub chains (Optimism, Base) use v2 routers with factory-aware Route structs.
+ * Leaf chains use the Relay router with simplified Route structs.
+ * @see https://velodrome.finance/docs
+ * @see https://aerodrome.finance/docs
+ */
+export const VELODROME_CHAINS: Partial<
+  Record<SupportedChainId, VelodromeChainConfig>
+> = {
+  [baseSepolia.id]: {
+    contracts: {
+      router: '0x4b94B729d6183c9efD0071f0790e984bAF46E093',
+      poolFactory: '0x7b9644D43900da734f5a83DD0489Af1197DF2CF0',
+    },
+    metadata: { routerType: 'universal' },
+  },
+  [optimism.id]: {
+    contracts: {
+      router: '0xa062aE8A9c5e11aaA026fc2670B0D65cCc8B2858',
+      poolFactory: '0xF1046053aa5682b4F9a81b5481394DA16BE5FF5a',
+      clPoolFactory: '0xCc0bDDB707055e04e497aB22a59c2aF4391cd12F',
+      clQuoterV2: '0x89D8218ed5fF1e46d8dcd33fb0bbeE3be1621466',
+    },
+    metadata: { routerType: 'v2' },
+  },
+  [base.id]: {
+    contracts: {
+      router: '0xcF77a3Ba9A5CA399B7c97c74d54e5b1Beb874E43',
+      poolFactory: '0x420DD381b31aEf6683db6B902084cB0FFECe40Da',
+      clPoolFactory: '0x5e7BB104d84c7CB9B682AaC2F3d509f5F406809A',
+      clQuoterV2: '0x254cF9E1E6e233aa1AC962CB9B05b2cfeAaE15b0',
+    },
+    metadata: { routerType: 'v2' },
+  },
+  [bob.id]: LEAF_CHAIN_CONFIG,
+  [celo.id]: LEAF_CHAIN_CONFIG,
+  [fraxtal.id]: LEAF_CHAIN_CONFIG,
+  [ink.id]: LEAF_CHAIN_CONFIG,
+  [lisk.id]: LEAF_CHAIN_CONFIG,
+  [metalL2.id]: LEAF_CHAIN_CONFIG,
+  [mode.id]: LEAF_CHAIN_CONFIG,
+  [soneium.id]: LEAF_CHAIN_CONFIG,
+  [superseed.id]: LEAF_CHAIN_CONFIG,
+  // Swell — not available in viem/chains
+  1923: LEAF_CHAIN_CONFIG,
+  [unichain.id]: LEAF_CHAIN_CONFIG,
+}

package/src/swap/providers/velodrome/config.ts

@@ -0,0 +1,46 @@
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+
+import { VELODROME_CHAINS, type VelodromeChainConfig } from './addresses.js'
+import type { VelodromeMarketConfig } from './types.js'
+
+export type {
+  VelodromeChainConfig,
+  VelodromeContracts,
+  VelodromeRouterType,
+} from './addresses.js'
+
+/**
+ * Get Velodrome/Aerodrome chain config including contracts and metadata.
+ * @param chainId - Target chain
+ * @returns Chain config with contracts and router type
+ * @throws If chain is not supported
+ */
+export function getChainConfig(
+  chainId: SupportedChainId,
+): VelodromeChainConfig {
+  const config = VELODROME_CHAINS[chainId]
+  if (!config) {
+    throw new Error(`Velodrome/Aerodrome not supported on chain ${chainId}`)
+  }
+  return config
+}
+
+/**
+ * Get all chain IDs where Velodrome/Aerodrome is deployed.
+ */
+export function getSupportedChainIds(): SupportedChainId[] {
+  return Object.keys(VELODROME_CHAINS).map(Number) as SupportedChainId[]
+}
+
+/**
+ * Filter market allowlist to configs with valid pool parameters.
+ * @param allowlist - Raw market allowlist from provider config
+ * @returns Configs that have either stable (v2) or tickSpacing (CL) set
+ */
+export function getValidMarketConfigs(
+  allowlist?: VelodromeMarketConfig[],
+): VelodromeMarketConfig[] {
+  return (allowlist ?? []).filter(
+    (f) => f.stable !== undefined || f.tickSpacing !== undefined,
+  )
+}