@eth-optimism/actions-sdk 0.2.0 → 0.4.0

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

@@ -0,0 +1,19 @@
+// 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'
+export type {
+  VelodromeMarketConfig,
+  VelodromeSwapProviderConfig,
+} from '@/swap/providers/velodrome/types.js'
+export { VelodromeSwapProvider } from '@/swap/providers/velodrome/VelodromeSwapProvider.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).
+ * Provides getQuote(), getMarket(), and getMarkets() for read-only access without a wallet.
+ */
+export class ActionsSwapNamespace extends BaseSwapNamespace {}

package/src/swap/namespaces/BaseSwapNamespace.ts

@@ -0,0 +1,258 @@
+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,
+  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,
+    protected readonly settings?: SwapSettings,
+  ) {}
+
+  /**
+   * 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 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 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,
+    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}`,
+    )
+  }
+
+  /**
+   * 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?, 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,
+    )
+  }
+
+  /**
+   * 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')
+    }
+
+    // 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

@@ -0,0 +1,121 @@
+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,
+} from '@/types/swap/index.js'
+import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+
+/**
+ * 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, settings)
+  }
+
+  /**
+   * Get a swap quote with the wallet address as recipient.
+   * Ensures calldata is encoded for the real wallet, not a placeholder.
+   */
+  override async getQuote(params: SwapQuoteParams): Promise<SwapQuote> {
+    return super.getQuote({
+      ...params,
+      recipient: params.recipient ?? this.wallet.address,
+    })
+  }
+
+  /**
+   * Get quotes from all providers with the wallet address as recipient.
+   */
+  override async getQuotes(params: SwapQuoteParams): Promise<SwapQuote[]> {
+    return super.getQuotes({
+      ...params,
+      recipient: params.recipient ?? this.wallet.address,
+    })
+  }
+
+  /**
+   * 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,
+      amountInRaw: swapTx.amountInRaw,
+      amountOutRaw: swapTx.amountOutRaw,
+      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)
+  }
+}