@eth-optimism/actions-sdk 0.3.0 → 0.4.0

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

@@ -43,6 +43,62 @@ describe('SwapProvider', () => {
       expect(provider.defaultSlippage).toBe(0.01)
     })
 
+    it('should use settings slippage when provider does not set one', () => {
+      const provider = new MockSwapProvider({}, undefined, undefined, {
+        defaultSlippage: 0.02,
+      })
+      expect(provider.defaultSlippage).toBe(0.02)
+    })
+
+    it('should prefer provider slippage over settings', () => {
+      const provider = new MockSwapProvider(
+        { defaultSlippage: 0.03 },
+        undefined,
+        undefined,
+        { defaultSlippage: 0.02 },
+      )
+      expect(provider.defaultSlippage).toBe(0.03)
+    })
+
+    it('should resolve maxSlippage: provider → settings → default', () => {
+      expect(new MockSwapProvider().maxSlippage).toBe(0.5)
+      expect(
+        new MockSwapProvider({}, undefined, undefined, { maxSlippage: 0.3 })
+          .maxSlippage,
+      ).toBe(0.3)
+      expect(
+        new MockSwapProvider({ maxSlippage: 0.1 }, undefined, undefined, {
+          maxSlippage: 0.3,
+        }).maxSlippage,
+      ).toBe(0.1)
+    })
+
+    it('should resolve quoteExpirationSeconds: provider → settings → default', () => {
+      expect(new MockSwapProvider().quoteExpirationSeconds).toBe(60)
+      expect(
+        new MockSwapProvider({}, undefined, undefined, {
+          quoteExpirationSeconds: 120,
+        }).quoteExpirationSeconds,
+      ).toBe(120)
+      expect(
+        new MockSwapProvider(
+          { quoteExpirationSeconds: 30 },
+          undefined,
+          undefined,
+          { quoteExpirationSeconds: 120 },
+        ).quoteExpirationSeconds,
+      ).toBe(30)
+    })
+
+    it('should resolve permit2ExpirationSeconds: provider → settings → default', () => {
+      expect(new MockSwapProvider().permit2ExpirationSeconds).toBe(2_592_000)
+      expect(
+        new MockSwapProvider({}, undefined, undefined, {
+          permit2ExpirationSeconds: 86400,
+        }).permit2ExpirationSeconds,
+      ).toBe(86400)
+    })
+
     it('should store market allowlist when provided', () => {
       const config: SwapMarketConfig = {
         assets: [MockUSDC, MockWETH],
@@ -148,7 +204,7 @@ describe('SwapProvider', () => {
 
       expect(provider.mockExecute).toHaveBeenCalledWith(
         expect.objectContaining({
-          amountInWei: 100000000n, // 100 * 10^6
+          amountInRaw: 100000000n, // 100 * 10^6
         }),
       )
     })
@@ -169,11 +225,11 @@ describe('SwapProvider', () => {
     })
   })
 
-  describe('getPrice()', () => {
+  describe('getQuote()', () => {
     it('should throw if chain not supported', async () => {
       const provider = new MockSwapProvider()
       await expect(
-        provider.getPrice({
+        provider.getQuote({
           assetIn: MockUSDC,
           assetOut: MockWETH,
           chainId: 999 as SupportedChainId,
@@ -181,19 +237,19 @@ describe('SwapProvider', () => {
       ).rejects.toThrow('Chain 999 is not supported')
     })
 
-    it('should return price quote', async () => {
+    it('should return quote', async () => {
       const provider = new MockSwapProvider()
-      const price = await provider.getPrice({
+      const quote = await provider.getQuote({
         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()
+      expect(quote.price).toBeDefined()
+      expect(quote.amountIn).toBeDefined()
+      expect(quote.amountOut).toBeDefined()
+      expect(quote.route).toBeDefined()
     })
   })
 
@@ -430,6 +486,92 @@ describe('SwapProvider', () => {
       ).not.toThrow()
     })
 
+    it('should filter blocked markets from getMarkets()', async () => {
+      const allowConfig: SwapMarketConfig = {
+        assets: [MockUSDC, MockWETH, MockOP],
+        chainId: 84532 as SupportedChainId,
+      }
+      const blockConfig: SwapMarketConfig = {
+        assets: [MockUSDC, MockOP],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({
+        marketAllowlist: [allowConfig],
+        marketBlocklist: [blockConfig],
+      })
+
+      // Mock _getMarkets to return markets with real assets
+      provider.mockGetMarkets.mockResolvedValue([
+        {
+          marketId: { poolId: '0xpool1', chainId: 84532 as SupportedChainId },
+          assets: [MockUSDC, MockWETH],
+          fee: 0,
+          provider: 'uniswap',
+        },
+        {
+          marketId: { poolId: '0xpool2', chainId: 84532 as SupportedChainId },
+          assets: [MockUSDC, MockOP],
+          fee: 0,
+          provider: 'uniswap',
+        },
+      ])
+
+      const markets = await provider.getMarkets()
+      // USDC/OP is blocklisted, only USDC/WETH should remain
+      expect(markets).toHaveLength(1)
+      expect(markets[0].assets[0]).toBe(MockUSDC)
+      expect(markets[0].assets[1]).toBe(MockWETH)
+    })
+
+    it('should reject blocked market from getMarket()', async () => {
+      const blockConfig: SwapMarketConfig = {
+        assets: [MockUSDC, MockOP],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({
+        marketBlocklist: [blockConfig],
+      })
+
+      // Mock _getMarket to return a blocked market
+      provider.mockGetMarket.mockResolvedValue({
+        marketId: { poolId: '0xpool1', chainId: 84532 as SupportedChainId },
+        assets: [MockUSDC, MockOP],
+        fee: 0,
+        provider: 'uniswap',
+      })
+
+      await expect(
+        provider.getMarket({
+          poolId: '0xpool1',
+          chainId: 84532 as SupportedChainId,
+        }),
+      ).rejects.toThrow('is blocked')
+    })
+
+    it('should allow non-blocked market from getMarket()', async () => {
+      const blockConfig: SwapMarketConfig = {
+        assets: [MockUSDC, MockOP],
+        chainId: 84532 as SupportedChainId,
+      }
+      const provider = new MockSwapProvider({
+        marketBlocklist: [blockConfig],
+      })
+
+      provider.mockGetMarket.mockResolvedValue({
+        marketId: { poolId: '0xpool1', chainId: 84532 as SupportedChainId },
+        assets: [MockUSDC, MockWETH],
+        fee: 0,
+        provider: 'uniswap',
+      })
+
+      const market = await provider.getMarket({
+        poolId: '0xpool1',
+        chainId: 84532 as SupportedChainId,
+      })
+      expect(market.assets[0]).toBe(MockUSDC)
+      expect(market.assets[1]).toBe(MockWETH)
+    })
+
     it('should scope filter to specific chainId when provided', () => {
       const multiChainUSDC: Asset = {
         ...MockUSDC,

package/src/swap/core/markets.ts

@@ -0,0 +1,104 @@
+import type { Address } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { Asset } from '@/types/asset.js'
+import type {
+  GetSwapMarketsParams,
+  SwapMarket,
+  SwapMarketConfig,
+} from '@/types/swap/index.js'
+
+/**
+ * Sentinel address meaning "send output to msg.sender" in Universal Router commands.
+ * The Universal Router maps address(1) to msg.sender and address(2) to the router itself.
+ * Only valid in Universal Router calldata encoding — do not use as a general-purpose address.
+ * Both Uniswap and Velodrome/Aerodrome Universal Router forks use this convention.
+ * @see https://github.com/Uniswap/universal-router/blob/main/contracts/libraries/Constants.sol
+ */
+export const UNIVERSAL_ROUTER_MSG_SENDER =
+  '0x0000000000000000000000000000000000000001' as Address
+
+/**
+ * Generate unique asset pairs, optionally filtered to pairs containing a required asset.
+ * @param assets - Full list of assets from a market config
+ * @param requiredAsset - If set, only pairs including this asset are returned
+ */
+export function assetPairs(
+  assets: Asset[],
+  requiredAsset?: Asset,
+): Array<[Asset, Asset]> {
+  return assets
+    .flatMap((a, i) => assets.slice(i + 1).map((b): [Asset, Asset] => [a, b]))
+    .filter(
+      ([a, b]) => !requiredAsset || a === requiredAsset || b === requiredAsset,
+    )
+}
+
+/**
+ * Sort two addresses for deterministic pool ID computation.
+ * @returns [lower, higher] addresses
+ */
+export function sortAddressPair(
+  addrA: string,
+  addrB: string,
+): [string, string] {
+  return addrA.toLowerCase() < addrB.toLowerCase()
+    ? [addrA, addrB]
+    : [addrB, addrA]
+}
+
+/**
+ * Find a specific market by poolId across a set of configs.
+ * @param configs - Valid market configs to search
+ * @param chainId - Target chain
+ * @param poolId - Pool ID to match
+ * @param toMarkets - Provider-specific function that expands a config into SwapMarket[]
+ * @returns Matching market
+ * @throws If no matching market found
+ */
+export function findMarket<T extends SwapMarketConfig>(
+  configs: T[],
+  chainId: SupportedChainId,
+  poolId: string,
+  toMarkets: (config: T, chainId: SupportedChainId) => SwapMarket[],
+): SwapMarket {
+  for (const config of configs) {
+    if (config.chainId !== undefined && config.chainId !== chainId) continue
+    const match = toMarkets(config, chainId).find(
+      (m) => m.marketId.poolId === poolId,
+    )
+    if (match) return match
+  }
+  throw new Error(`Market with poolId ${poolId} not found on chain ${chainId}`)
+}
+
+/**
+ * Expand market configs into concrete SwapMarket objects with optional filters.
+ * @param options.configs - Valid market configs
+ * @param options.filters - Optional chainId and asset filters
+ * @param options.supportedChainIds - All chain IDs this provider supports
+ * @param options.toMarkets - Provider-specific function that expands a config into SwapMarket[]
+ */
+export function expandMarkets<T extends SwapMarketConfig>(options: {
+  configs: T[]
+  filters: GetSwapMarketsParams
+  supportedChainIds: SupportedChainId[]
+  toMarkets: (
+    config: T,
+    chainId: SupportedChainId,
+    asset?: Asset,
+  ) => SwapMarket[]
+}): SwapMarket[] {
+  const { configs, filters, supportedChainIds, toMarkets } = options
+  return configs.flatMap((config) => {
+    const chainIds = filters.chainId
+      ? [filters.chainId]
+      : config.chainId
+        ? [config.chainId]
+        : supportedChainIds
+
+    return chainIds.flatMap((chainId) =>
+      toMarkets(config, chainId, filters.asset),
+    )
+  })
+}

package/src/swap/index.ts

@@ -12,3 +12,8 @@ export type {
   UniswapSwapProviderConfig,
 } from '@/swap/providers/uniswap/types.js'
 export { UniswapSwapProvider } from '@/swap/providers/uniswap/UniswapSwapProvider.js'
+export type {
+  VelodromeMarketConfig,
+  VelodromeSwapProviderConfig,
+} from '@/swap/providers/velodrome/types.js'
+export { VelodromeSwapProvider } from '@/swap/providers/velodrome/VelodromeSwapProvider.js'

package/src/swap/namespaces/ActionsSwapNamespace.ts

@@ -1,7 +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
+ * Actions swap namespace (read-only, no wallet required).
+ * Provides getQuote(), getMarket(), and getMarkets() for read-only access without a wallet.
  */
 export class ActionsSwapNamespace extends BaseSwapNamespace {}

package/src/swap/namespaces/BaseSwapNamespace.ts

@@ -1,37 +1,169 @@
 import type { SupportedChainId } from '@/constants/supportedChains.js'
 import type { SwapProvider } from '@/swap/core/SwapProvider.js'
+import type { SwapProviderName, SwapSettings } from '@/types/actions.js'
+import type { Asset } from '@/types/asset.js'
 import type {
   GetSwapMarketParams,
   GetSwapMarketsParams,
   SwapMarket,
-  SwapPrice,
-  SwapPriceParams,
   SwapProviderConfig,
   SwapProviders,
+  SwapQuote,
+  SwapQuoteParams,
 } from '@/types/swap/index.js'
 
 /**
  * Base swap namespace with shared read-only operations
  */
 export abstract class BaseSwapNamespace {
-  constructor(protected readonly providers: SwapProviders) {}
+  constructor(
+    protected readonly providers: SwapProviders,
+    protected readonly settings?: SwapSettings,
+  ) {}
 
   /**
-   * Get price quote for a swap
+   * Get a swap quote with pre-built execution data.
+   * When `routing: 'price'` is set in settings and no explicit provider is requested,
+   * fetches quotes from all eligible providers in parallel and returns the best price.
+   * @param params - Quote parameters (assets, amounts, chain, optional provider)
+   * @returns The best available SwapQuote
    */
-  async price(params: SwapPriceParams): Promise<SwapPrice> {
-    const provider = this.getProvider()
-    return provider.getPrice(params)
+  async getQuote(params: SwapQuoteParams): Promise<SwapQuote> {
+    // Explicit provider — skip routing
+    if (params.provider) {
+      const provider = this.resolveProvider(
+        params.provider,
+        params.assetIn,
+        params.assetOut,
+        params.chainId,
+      )
+      return provider.getQuote(params)
+    }
+
+    // Price routing — quote all eligible providers, return best
+    if (this.settings?.routing === 'price') {
+      return this.getBestQuote(params)
+    }
+
+    // No routing — resolve single provider via fallback logic
+    const provider = this.resolveProvider(
+      undefined,
+      params.assetIn,
+      params.assetOut,
+      params.chainId,
+    )
+    return provider.getQuote(params)
+  }
+
+  /**
+   * Fetch quotes from all eligible providers in parallel and return the best.
+   * @param params - Quote parameters
+   * @returns The quote with the highest amountOut
+   * @throws If no provider returns a valid quote
+   */
+  private async getBestQuote(params: SwapQuoteParams): Promise<SwapQuote> {
+    const quotes = await this.fetchAllQuotes(params)
+
+    let best: SwapQuote | null = null
+    for (const quote of quotes) {
+      if (!best || quote.amountOutRaw > best.amountOutRaw) {
+        best = quote
+      }
+    }
+
+    if (!best) {
+      throw new Error(
+        `All providers failed to quote ${params.assetIn.metadata.symbol}/${params.assetOut.metadata.symbol}`,
+      )
+    }
+
+    return best
+  }
+
+  /**
+   * Fetch quotes from all eligible providers in parallel.
+   * Providers that don't support the pair or fail to quote are silently skipped.
+   * @param params - Quote parameters
+   * @returns Array of successful quotes (may be empty if all providers fail)
+   */
+  private async fetchAllQuotes(params: SwapQuoteParams): Promise<SwapQuote[]> {
+    const eligible = this.getAllProviders().filter((p) =>
+      p.isMarketSupported(params.assetIn, params.assetOut, params.chainId),
+    )
+
+    if (eligible.length === 0) {
+      throw new Error(
+        `No provider supports ${params.assetIn.metadata.symbol}/${params.assetOut.metadata.symbol} on chain ${params.chainId}`,
+      )
+    }
+
+    const results = await Promise.allSettled(
+      eligible.map((p) => p.getQuote(params)),
+    )
+
+    return results
+      .filter(
+        (r): r is PromiseFulfilledResult<SwapQuote> => r.status === 'fulfilled',
+      )
+      .map((r) => r.value)
+  }
+
+  /**
+   * Fetch quotes from all eligible providers in parallel.
+   * Unlike getQuote(), returns all successful quotes instead of just the best.
+   * If an explicit provider is specified, returns a single-element array from that provider.
+   * @param params - Quote parameters (assets, amounts, chain, optional provider)
+   * @returns Array of SwapQuotes sorted by amountOut descending (best first)
+   */
+  async getQuotes(params: SwapQuoteParams): Promise<SwapQuote[]> {
+    if (params.provider) {
+      const provider = this.resolveProvider(
+        params.provider,
+        params.assetIn,
+        params.assetOut,
+        params.chainId,
+      )
+      return [await provider.getQuote(params)]
+    }
+
+    const quotes = await this.fetchAllQuotes(params)
+    return quotes.sort((a, b) =>
+      a.amountOutRaw > b.amountOutRaw
+        ? -1
+        : a.amountOutRaw < b.amountOutRaw
+          ? 1
+          : 0,
+    )
   }
 
   /**
-   * Get a specific swap market
-   * @param params - Market identifier
+   * Get a specific swap market by ID.
+   * @param params - Market identifier (poolId + chainId)
+   * @param provider - Optional provider name to query directly instead of searching all
    * @returns Market information
    */
-  async getMarket(params: GetSwapMarketParams): Promise<SwapMarket> {
-    const provider = this.getProvider()
-    return provider.getMarket(params)
+  async getMarket(
+    params: GetSwapMarketParams,
+    provider?: SwapProviderName,
+  ): Promise<SwapMarket> {
+    if (provider) {
+      const named = this.providers[provider]
+      if (!named) {
+        throw new Error(`Swap provider "${provider}" not configured`)
+      }
+      return named.getMarket(params)
+    }
+
+    for (const p of this.getAllProviders()) {
+      try {
+        return await p.getMarket(params)
+      } catch {
+        continue
+      }
+    }
+    throw new Error(
+      `Market with poolId ${params.poolId} not found on chain ${params.chainId}`,
+    )
   }
 
   /**
@@ -59,19 +191,68 @@ export abstract class BaseSwapNamespace {
     return Array.from(chainIds)
   }
 
-  // SwapProviders keys are optional (uniswap?, aerodrome?, etc.) so filter out unconfigured ones
+  // SwapProviders keys are optional (uniswap?, velodrome?, 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) {
+  /**
+   * Resolve which provider handles a request.
+   *
+   * Precedence:
+   * 1. Explicit `provider` param on the call
+   * 2. routing.defaultProvider (when no strategy set)
+   * 3. routing.strategy match (market-aware, defaultProvider as tiebreaker)
+   * 4. First provider whose allowlist matches
+   * 5. First configured provider
+   */
+  protected resolveProvider(
+    provider: SwapProviderName | undefined,
+    assetIn: Asset,
+    assetOut: Asset,
+    chainId: SupportedChainId,
+  ): SwapProvider<SwapProviderConfig> {
+    const allProviders = this.getAllProviders()
+    if (allProviders.length === 0) {
       throw new Error('No swap provider configured')
     }
-    return provider
+
+    // 1. Explicit provider param
+    if (provider) {
+      const named = this.providers[provider]
+      if (!named) {
+        throw new Error(`Swap provider "${provider}" not configured`)
+      }
+      return named
+    }
+
+    // Single provider — no routing needed
+    if (allProviders.length === 1) {
+      return allProviders[0]
+    }
+
+    // 2. defaultProvider with no routing strategy — always use it
+    if (this.settings?.defaultProvider && !this.settings.routing) {
+      const provider = this.providers[this.settings.defaultProvider]
+      if (provider) return provider
+    }
+
+    // 3. Match by market allowlist
+    for (const p of allProviders) {
+      if (p.isMarketSupported(assetIn, assetOut, chainId)) {
+        return p
+      }
+    }
+
+    // 4. Match by chain support
+    for (const p of allProviders) {
+      if (p.isChainSupported(chainId)) {
+        return p
+      }
+    }
+
+    return allProviders[0]
   }
 }

package/src/swap/namespaces/WalletSwapNamespace.ts

@@ -1,7 +1,11 @@
 import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { QUOTE_DISCRIMINATOR } from '@/swap/core/SwapProvider.js'
 import { BaseSwapNamespace } from '@/swap/namespaces/BaseSwapNamespace.js'
+import type { SwapSettings } from '@/types/actions.js'
 import type {
   SwapProviders,
+  SwapQuote,
+  SwapQuoteParams,
   SwapReceipt,
   SwapTransaction,
   WalletSwapParams,
@@ -9,40 +13,75 @@ import type {
 import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
 
 /**
- * Wallet swap namespace (full operations with signing)
- * @description Provides execute() for swapping tokens
+ * Wallet swap namespace with full operations including signing.
+ * Provides getQuote() for pricing and execute() for swapping tokens.
  */
 export class WalletSwapNamespace extends BaseSwapNamespace {
   constructor(
     providers: SwapProviders,
     private readonly wallet: Wallet,
+    settings?: SwapSettings,
   ) {
-    super(providers)
+    super(providers, settings)
   }
 
   /**
-   * Execute a token swap
-   * @param params - Swap parameters including chainId
-   * @returns Swap receipt with transaction details
+   * Get a swap quote with the wallet address as recipient.
+   * Ensures calldata is encoded for the real wallet, not a placeholder.
    */
-  async execute(params: WalletSwapParams): Promise<SwapReceipt> {
-    const provider = this.getProvider()
+  override async getQuote(params: SwapQuoteParams): Promise<SwapQuote> {
+    return super.getQuote({
+      ...params,
+      recipient: params.recipient ?? this.wallet.address,
+    })
+  }
 
-    // Build swap transaction
-    const swapTx = await provider.execute({
+  /**
+   * Get quotes from all providers with the wallet address as recipient.
+   */
+  override async getQuotes(params: SwapQuoteParams): Promise<SwapQuote[]> {
+    return super.getQuotes({
       ...params,
-      walletAddress: this.wallet.address,
+      recipient: params.recipient ?? this.wallet.address,
     })
+  }
 
-    // Execute transaction(s)
+  /**
+   * Execute a token swap.
+   * Accepts either raw params (re-quotes internally) or a pre-built SwapQuote (skips re-quoting).
+   * @param params - Swap parameters or a pre-built SwapQuote from getQuote()
+   * @returns Swap receipt with transaction details
+   */
+  async execute(params: WalletSwapParams | SwapQuote): Promise<SwapReceipt> {
+    // Inject walletAddress — raw params need it for validation,
+    // quotes need it for on-chain allowance checks during approval building
+    const executeParams =
+      QUOTE_DISCRIMINATOR in params
+        ? { ...params, recipient: this.wallet.address }
+        : { ...params, walletAddress: this.wallet.address }
+
+    const provider = this.resolveProvider(
+      params.provider,
+      params.assetIn,
+      params.assetOut,
+      params.chainId,
+    )
+
+    const swapTx = await provider.execute(executeParams)
     const receipt = await this.executeTransaction(swapTx, params.chainId)
+    return this.buildReceipt(swapTx, receipt)
+  }
 
+  private buildReceipt(
+    swapTx: SwapTransaction,
+    receipt: SwapReceipt['receipt'],
+  ): SwapReceipt {
     return {
       receipt,
       amountIn: swapTx.amountIn,
       amountOut: swapTx.amountOut,
-      amountInWei: swapTx.amountInWei,
-      amountOutWei: swapTx.amountOutWei,
+      amountInRaw: swapTx.amountInRaw,
+      amountOutRaw: swapTx.amountOutRaw,
       assetIn: swapTx.assetIn,
       assetOut: swapTx.assetOut,
       price: swapTx.price,