@eth-optimism/actions-sdk 0.5.0 → 0.6.0

package/src/{swap → actions/swap}/namespaces/ActionsSwapNamespace.ts

@@ -1,4 +1,4 @@
-import { BaseSwapNamespace } from '@/swap/namespaces/BaseSwapNamespace.js'
+import { BaseSwapNamespace } from '@/actions/swap/namespaces/BaseSwapNamespace.js'
 
 /**
  * Actions swap namespace (read-only, no wallet required).

package/src/{swap → actions/swap}/namespaces/BaseSwapNamespace.ts

@@ -1,6 +1,16 @@
+import { BaseNamespace } from '@/actions/shared/BaseNamespace.js'
+import type { SwapProvider } from '@/actions/swap/core/SwapProvider.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import type { SwapQuoteParamsResolved } from '@/ens/types.js'
-import type { SwapProvider } from '@/swap/core/SwapProvider.js'
+import {
+  MarketNotAllowedError,
+  MarketNotFoundError,
+  ProviderNotConfiguredError,
+} from '@/core/error/errors.js'
+import type { SwapQuoteParamsResolved } from '@/services/nameservices/ens/types.js'
+import {
+  passthroughResolver,
+  type RecipientResolver,
+} from '@/services/nameservices/ens/utils.js'
 import type { SwapProviderName, SwapSettings } from '@/types/actions.js'
 import type { Asset } from '@/types/asset.js'
 import type {
@@ -12,19 +22,24 @@ import type {
   SwapQuote,
   SwapQuoteParams,
 } from '@/types/swap/index.js'
-import { passthroughResolver, type RecipientResolver } from '@/utils/ens.js'
+
+type ConfiguredSwapProvider = SwapProvider<SwapProviderConfig>
 
 /**
  * Base swap namespace with shared read-only operations
  */
-export abstract class BaseSwapNamespace {
+export abstract class BaseSwapNamespace extends BaseNamespace<
+  ConfiguredSwapProvider,
+  SwapProviders
+> {
   protected readonly resolveRecipient: RecipientResolver
 
   constructor(
-    protected readonly providers: SwapProviders,
+    providers: SwapProviders,
     resolveRecipient?: RecipientResolver,
     protected readonly settings?: SwapSettings,
   ) {
+    super(providers)
     this.resolveRecipient = resolveRecipient ?? passthroughResolver
   }
 
@@ -64,64 +79,7 @@ export abstract class BaseSwapNamespace {
   }
 
   /**
-   * 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: SwapQuoteParamsResolved,
-  ): 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: SwapQuoteParamsResolved,
-  ): 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.
+   * Fetch quotes from all providers with the wallet address as recipient.
    * 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)
@@ -165,7 +123,7 @@ export abstract class BaseSwapNamespace {
     if (provider) {
       const named = this.providers[provider]
       if (!named) {
-        throw new Error(`Swap provider "${provider}" not configured`)
+        throw new ProviderNotConfiguredError({ provider })
       }
       return named.getMarket(params)
     }
@@ -177,9 +135,10 @@ export abstract class BaseSwapNamespace {
         continue
       }
     }
-    throw new Error(
-      `Market with poolId ${params.poolId} not found on chain ${params.chainId}`,
-    )
+    throw new MarketNotFoundError({
+      chainId: params.chainId,
+      poolId: params.poolId,
+    })
   }
 
   /**
@@ -194,26 +153,6 @@ export abstract class BaseSwapNamespace {
     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.
    *
@@ -229,17 +168,17 @@ export abstract class BaseSwapNamespace {
     assetIn: Asset,
     assetOut: Asset,
     chainId: SupportedChainId,
-  ): SwapProvider<SwapProviderConfig> {
+  ): ConfiguredSwapProvider {
     const allProviders = this.getAllProviders()
     if (allProviders.length === 0) {
-      throw new Error('No swap provider configured')
+      throw new ProviderNotConfiguredError({ provider: 'swap' })
     }
 
     // 1. Explicit provider param
     if (provider) {
       const named = this.providers[provider]
       if (!named) {
-        throw new Error(`Swap provider "${provider}" not configured`)
+        throw new ProviderNotConfiguredError({ provider })
       }
       return named
     }
@@ -271,4 +210,67 @@ export abstract class BaseSwapNamespace {
 
     return allProviders[0]
   }
+
+  /**
+   * 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: SwapQuoteParamsResolved,
+  ): 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 MarketNotAllowedError({
+        assetInSymbol: params.assetIn.metadata.symbol,
+        assetOutSymbol: params.assetOut.metadata.symbol,
+        chainId: params.chainId,
+        reason: 'All providers failed to quote this pair',
+      })
+    }
+
+    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: SwapQuoteParamsResolved,
+  ): Promise<SwapQuote[]> {
+    const eligible = this.getAllProviders().filter((p) =>
+      p.isMarketSupported(params.assetIn, params.assetOut, params.chainId),
+    )
+
+    if (eligible.length === 0) {
+      throw new MarketNotAllowedError({
+        assetInSymbol: params.assetIn.metadata.symbol,
+        assetOutSymbol: params.assetOut.metadata.symbol,
+        chainId: params.chainId,
+        reason: 'No configured provider supports this pair on this chain',
+      })
+    }
+
+    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)
+  }
 }

package/src/actions/swap/namespaces/WalletSwapNamespace.ts

@@ -0,0 +1,154 @@
+import { isAddressEqual } from 'viem'
+
+import { QUOTE_DISCRIMINATOR } from '@/actions/swap/core/SwapProvider.js'
+import { BaseSwapNamespace } from '@/actions/swap/namespaces/BaseSwapNamespace.js'
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { SwapExecuteParamsResolved } from '@/services/nameservices/ens/types.js'
+import type { RecipientResolver } from '@/services/nameservices/ens/utils.js'
+import type { SwapSettings } from '@/types/actions.js'
+import type {
+  SwapProviders,
+  SwapQuote,
+  SwapQuoteParams,
+  SwapReceipt,
+  SwapTransaction,
+  WalletSwapParams,
+} from '@/types/swap/index.js'
+import type { TransactionData } from '@/types/transaction.js'
+import { executeTransactionBatch } from '@/wallet/core/utils/executeTransactionBatch.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,
+    resolveRecipient?: RecipientResolver,
+    settings?: SwapSettings,
+  ) {
+    super(providers, resolveRecipient, 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). When a pre-built quote is passed, its recipient must
+   * equal this wallet's address — otherwise the calldata would route output
+   * tokens to a different address (a real risk on Velodrome v2/leaf paths
+   * where the recipient is encoded directly into the swap call). Re-quote via
+   * `wallet.swap.getQuote(...)` to bind the quote to this wallet.
+   * @param params - Swap parameters or a pre-built SwapQuote from getQuote()
+   * @returns Swap receipt with transaction details
+   * @throws If `params` is a SwapQuote whose recipient differs from this wallet
+   */
+  async execute(params: WalletSwapParams | SwapQuote): Promise<SwapReceipt> {
+    const executeParams =
+      QUOTE_DISCRIMINATOR in params
+        ? this.requireQuoteForThisWallet(params)
+        : await this.resolveRawParams(params)
+
+    const provider = this.resolveProvider(
+      params.provider,
+      params.assetIn,
+      params.assetOut,
+      params.chainId,
+    )
+
+    const swapTx = await provider.execute(executeParams)
+    const receipt = await this.dispatch(swapTx, params.chainId)
+    return this.buildReceipt(swapTx, receipt)
+  }
+
+  /**
+   * Validate that a pre-built quote is bound to this wallet. Throws when the
+   * quote's recipient differs from `wallet.address` — silently swapping
+   * recipients would route output tokens to the wrong address on routers that
+   * encode the recipient directly into calldata (e.g. Velodrome v2/leaf).
+   */
+  private requireQuoteForThisWallet(quote: SwapQuote): SwapQuote {
+    if (!isAddressEqual(quote.recipient, this.wallet.address)) {
+      throw new Error(
+        `SwapQuote was generated for a different recipient (${quote.recipient}). ` +
+          `Re-quote via wallet.swap.getQuote(...) so calldata is bound to this wallet (${this.wallet.address}).`,
+      )
+    }
+    return quote
+  }
+
+  /**
+   * Inject `walletAddress` (needed for validation and on-chain allowance
+   * checks) and resolve any ENS recipient so providers only ever receive an
+   * `Address`.
+   */
+  private async resolveRawParams(
+    params: WalletSwapParams,
+  ): Promise<SwapExecuteParamsResolved> {
+    return {
+      ...params,
+      walletAddress: this.wallet.address,
+      recipient: await this.resolveRecipient(
+        params.recipient ?? this.wallet.address,
+      ),
+    }
+  }
+
+  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,
+    }
+  }
+
+  /**
+   * Send a swap transaction, collecting any token/Permit2 approvals ahead
+   * of the swap call. Defers to `executeTransactionBatch` for the actual
+   * 1-vs-N send/sendBatch dispatch.
+   */
+  private dispatch(
+    swapTx: SwapTransaction,
+    chainId: SupportedChainId,
+  ): Promise<SwapReceipt['receipt']> {
+    const { transactionData } = swapTx
+    const txs: TransactionData[] = []
+    if (transactionData.tokenApproval) txs.push(transactionData.tokenApproval)
+    if (transactionData.permit2Approval) {
+      txs.push(transactionData.permit2Approval)
+    }
+    txs.push(transactionData.swap)
+    return executeTransactionBatch(this.wallet, txs, chainId)
+  }
+}

package/src/{swap → actions/swap}/namespaces/__tests__/BaseSwapNamespace.spec.ts

@@ -1,13 +1,13 @@
 import { describe, expect, it } from 'vitest'
 
-import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { MockChainManager } from '@/services/__mocks__/MockChainManager.js'
-import type { ChainManager } from '@/services/ChainManager.js'
 import {
   createMockSwapProvider,
   MockSwapProvider,
-} from '@/swap/__mocks__/MockSwapProvider.js'
-import { ActionsSwapNamespace } from '@/swap/namespaces/ActionsSwapNamespace.js'
+} from '@/actions/swap/__mocks__/MockSwapProvider.js'
+import { ActionsSwapNamespace } from '@/actions/swap/namespaces/ActionsSwapNamespace.js'
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { MockChainManager } from '@/services/__mocks__/MockChainManager.js'
+import type { ChainManager } from '@/services/ChainManager.js'
 
 describe('BaseSwapNamespace', () => {
   const USDC = {
@@ -50,7 +50,7 @@ describe('BaseSwapNamespace', () => {
           amountIn: 100,
           chainId: 84532 as SupportedChainId,
         }),
-      ).rejects.toThrow('No swap provider configured')
+      ).rejects.toThrow("A 'swap' provider is not configured")
     })
   })
 

package/src/{swap → actions/swap}/namespaces/__tests__/WalletSwapNamespace.spec.ts

@@ -1,9 +1,9 @@
 import type { Address } from 'viem'
 import { describe, expect, it, vi } from 'vitest'
 
+import { createMockSwapProvider } from '@/actions/swap/__mocks__/MockSwapProvider.js'
+import { WalletSwapNamespace } from '@/actions/swap/namespaces/WalletSwapNamespace.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { createMockSwapProvider } from '@/swap/__mocks__/MockSwapProvider.js'
-import { WalletSwapNamespace } from '@/swap/namespaces/WalletSwapNamespace.js'
 import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
 
 describe('WalletSwapNamespace', () => {
@@ -118,6 +118,47 @@ describe('WalletSwapNamespace', () => {
       )
     })
 
+    it('defaults recipient to wallet address when omitted', async () => {
+      const provider = createMockSwapProvider()
+      const wallet = createMockWallet()
+      const namespace = new WalletSwapNamespace({ uniswap: provider }, wallet)
+
+      await namespace.execute({
+        amountIn: 100,
+        assetIn: USDC,
+        assetOut: ETH,
+        chainId: 84532 as SupportedChainId,
+      })
+
+      expect(provider.mockExecute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          recipient: mockWalletAddress,
+        }),
+      )
+    })
+
+    it('preserves explicit recipient over wallet address', async () => {
+      const provider = createMockSwapProvider()
+      const wallet = createMockWallet()
+      const namespace = new WalletSwapNamespace({ uniswap: provider }, wallet)
+      const customRecipient =
+        '0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' as Address
+
+      await namespace.execute({
+        amountIn: 100,
+        assetIn: USDC,
+        assetOut: ETH,
+        chainId: 84532 as SupportedChainId,
+        recipient: customRecipient,
+      })
+
+      expect(provider.mockExecute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          recipient: customRecipient,
+        }),
+      )
+    })
+
     it('throws when no provider configured', async () => {
       const wallet = createMockWallet()
       const namespace = new WalletSwapNamespace({}, wallet)
@@ -129,7 +170,7 @@ describe('WalletSwapNamespace', () => {
           assetOut: ETH,
           chainId: 84532 as SupportedChainId,
         }),
-      ).rejects.toThrow('No swap provider configured')
+      ).rejects.toThrow("A 'swap' provider is not configured")
     })
 
     it('executes swap from a SwapQuote (skips re-quoting)', async () => {
@@ -170,7 +211,7 @@ describe('WalletSwapNamespace', () => {
       })
 
       // Quote should have wallet address as the encoded recipient
-      expect(quote.quotedRecipient).toBe(mockWalletAddress)
+      expect(quote.recipient).toBe(mockWalletAddress)
     })
 
     it('preserves explicit recipient over wallet address', async () => {
@@ -188,43 +229,61 @@ describe('WalletSwapNamespace', () => {
         recipient: customRecipient,
       })
 
-      expect(quote.quotedRecipient).toBe(customRecipient)
+      expect(quote.recipient).toBe(customRecipient)
     })
   })
 
   describe('execute with recipient mismatch', () => {
-    it('re-encodes when quote recipient differs from wallet', async () => {
+    it('throws when quote.recipient does not match wallet.address', async () => {
       const provider = createMockSwapProvider()
       const wallet = createMockWallet()
       const namespace = new WalletSwapNamespace({ uniswap: provider }, wallet)
 
-      // Get quote without wallet (simulates ActionsSwapNamespace quote)
+      // Get quote without wallet (simulates ActionsSwapNamespace quote — recipient
+      // defaults to UNIVERSAL_ROUTER_MSG_SENDER, not the executing wallet)
       const quote = await provider.getQuote({
         assetIn: USDC,
         assetOut: ETH,
         amountIn: 100,
         chainId: 84532 as SupportedChainId,
-        // No recipient — uses placeholder
       })
 
-      // quotedRecipient should be the placeholder, not the wallet
-      expect(quote.quotedRecipient).not.toBe(mockWalletAddress)
+      expect(quote.recipient).not.toBe(mockWalletAddress)
 
-      // Execute through wallet namespace — should re-quote with correct recipient
-      const result = await namespace.execute(quote)
-      expect(result.price).toBeDefined()
+      await expect(namespace.execute(quote)).rejects.toThrow(
+        /generated for a different recipient/i,
+      )
+      // Provider's getQuote was called once (the original); execute did not re-quote.
+      expect(provider.mockGetQuote).toHaveBeenCalledTimes(1)
+    })
+
+    it('throws on a quote built for a different wallet address', async () => {
+      const provider = createMockSwapProvider()
+      const wallet = createMockWallet()
+      const namespace = new WalletSwapNamespace({ uniswap: provider }, wallet)
+      const otherWallet =
+        '0x9999999999999999999999999999999999999999' as Address
+
+      const quote = await provider.getQuote({
+        assetIn: USDC,
+        assetOut: ETH,
+        amountIn: 100,
+        chainId: 84532 as SupportedChainId,
+        recipient: otherWallet,
+      })
+
+      expect(quote.recipient).toBe(otherWallet)
 
-      // Provider's getQuote should have been called twice:
-      // 1) original quote, 2) re-quote with wallet address
-      expect(provider.mockGetQuote).toHaveBeenCalledTimes(2)
+      await expect(namespace.execute(quote)).rejects.toThrow(
+        /generated for a different recipient/i,
+      )
     })
 
-    it('skips re-encode when quote already has correct recipient', async () => {
+    it('executes when quote.recipient equals wallet.address', async () => {
       const provider = createMockSwapProvider()
       const wallet = createMockWallet()
       const namespace = new WalletSwapNamespace({ uniswap: provider }, wallet)
 
-      // Get quote through wallet namespace (has correct recipient)
       const quote = await namespace.getQuote({
         assetIn: USDC,
         assetOut: ETH,
@@ -232,15 +291,44 @@ describe('WalletSwapNamespace', () => {
         chainId: 84532 as SupportedChainId,
       })
 
-      expect(quote.quotedRecipient).toBe(mockWalletAddress)
+      expect(quote.recipient).toBe(mockWalletAddress)
 
-      // Execute — should NOT re-quote
       const result = await namespace.execute(quote)
       expect(result.price).toBeDefined()
-
-      // getQuote called only once (the original)
+      // Single getQuote call — no re-quote, no re-encode.
       expect(provider.mockGetQuote).toHaveBeenCalledTimes(1)
     })
+
+    it('executes when quote.recipient differs only in case from wallet.address', async () => {
+      // Address with hex letters so case actually changes the string. The
+      // wallet uses checksummed casing; the quote uses lowercase. Without
+      // `isAddressEqual` the strict `!==` would falsely reject.
+      const checksummedAddress =
+        '0xAbCdEf1234567890aBcDeF1234567890ABcDeF12' as Address
+      const lowercaseAddress = checksummedAddress.toLowerCase() as Address
+
+      const provider = createMockSwapProvider()
+      const wallet = {
+        address: checksummedAddress,
+        send: vi.fn().mockResolvedValue({ transactionHash: '0xtx1' }),
+        sendBatch: vi.fn().mockResolvedValue({ transactionHash: '0xtx2' }),
+      } as unknown as Wallet
+      const namespace = new WalletSwapNamespace({ uniswap: provider }, wallet)
+
+      const quote = await provider.getQuote({
+        assetIn: USDC,
+        assetOut: ETH,
+        amountIn: 100,
+        chainId: 84532 as SupportedChainId,
+        recipient: lowercaseAddress,
+      })
+
+      expect(quote.recipient).toBe(lowercaseAddress)
+      expect(quote.recipient).not.toBe(checksummedAddress)
+
+      const result = await namespace.execute(quote)
+      expect(result.price).toBeDefined()
+    })
   })
 
   describe('inherits read-only methods', () => {