@eth-optimism/actions-sdk 0.5.0 → 0.6.0

package/src/{lend → actions/lend}/providers/morpho/__tests__/sdk.test.ts

@@ -1,11 +1,11 @@
 import { mainnet } from 'viem/chains'
 import { describe, expect, it } from 'vitest'
 
-import { MORPHO, USDC } from '@/constants/assets.js'
 import {
   calculateBaseApy,
   calculateRewardsBreakdown,
-} from '@/lend/providers/morpho/sdk.js'
+} from '@/actions/lend/providers/morpho/sdk.js'
+import { MORPHO, USDC } from '@/constants/assets.js'
 
 const CHAIN_ID = mainnet.id
 const USDC_ADDRESS = USDC.address[CHAIN_ID]!.toLowerCase()

package/src/{lend → actions/lend}/providers/morpho/sdk.ts

@@ -7,12 +7,18 @@ import {
 } from '@morpho-org/blue-sdk-viem'
 import type { Address, PublicClient } from 'viem'
 
-import { NATIVELY_SUPPORTED_ASSETS } from '@/constants/assets.js'
 import {
   fetchRewards,
   type RewardsBreakdown,
-} from '@/lend/providers/morpho/api.js'
-import { getMorphoContracts } from '@/lend/providers/morpho/contracts.js'
+} from '@/actions/lend/providers/morpho/api.js'
+import { getMorphoContracts } from '@/actions/shared/morpho/contracts.js'
+import type { MorphoContracts } from '@/actions/shared/morpho/types.js'
+import { NATIVELY_SUPPORTED_ASSETS } from '@/constants/assets.js'
+import {
+  ChainNotSupportedError,
+  MarketNotAllowedError,
+  ProviderNotConfiguredError,
+} from '@/core/error/errors.js'
 import type { ChainManager } from '@/services/ChainManager.js'
 import type { LendProviderConfig } from '@/types/actions.js'
 import type { Asset } from '@/types/asset.js'
@@ -21,7 +27,6 @@ import type {
   LendMarket,
   LendMarketConfig,
   LendMarketId,
-  MorphoContracts,
 } from '@/types/lend/index.js'
 import { SECONDS_PER_YEAR } from '@/utils/constants.js'
 
@@ -337,9 +342,11 @@ export async function getVault(params: GetVaultParams): Promise<LendMarket> {
     : undefined
 
   if (!marketConfig) {
-    throw new Error(
-      `Market ${params.marketId.address} on chain ${params.marketId.chainId} not found in allowlist`,
-    )
+    throw new MarketNotAllowedError({
+      address: params.marketId.address,
+      chainId: params.marketId.chainId,
+      reason: 'Market not found in allowlist',
+    })
   }
 
   const publicClient = params.chainManager.getPublicClient(
@@ -400,9 +407,7 @@ export async function getVault(params: GetVaultParams): Promise<LendMarket> {
   }
 
   // No SDK support and no contracts configured
-  throw new Error(
-    `Chain ${params.marketId.chainId} not supported by Morpho SDK and no contracts configured`,
-  )
+  throw new ChainNotSupportedError({ chainId: params.marketId.chainId })
 }
 
 interface GetVaultsParams {
@@ -447,7 +452,10 @@ export async function findBestVaultForAsset(
   marketAllowlist: LendMarketConfig[],
 ): Promise<Address> {
   if (!marketAllowlist || marketAllowlist.length === 0) {
-    throw new Error('Market allowlist is required and cannot be empty')
+    throw new ProviderNotConfiguredError({
+      provider: 'marketAllowlist',
+      details: 'Market allowlist is required and cannot be empty',
+    })
   }
 
   const assetVaults = marketAllowlist.filter((vault) => {
@@ -456,7 +464,10 @@ export async function findBestVaultForAsset(
   })
 
   if (assetVaults.length === 0) {
-    throw new Error(`No vaults available for asset ${asset}`)
+    throw new MarketNotAllowedError({
+      chainId: 0,
+      reason: `No vaults available for asset ${asset}`,
+    })
   }
 
   // For now, return the first (and only) supported vault for the asset

package/src/actions/lend/utils/markets.ts

@@ -0,0 +1,62 @@
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { MarketNotAllowedError } from '@/core/error/errors.js'
+import type { Asset } from '@/types/asset.js'
+import type {
+  LendMarket,
+  LendMarketConfig,
+  LendMarketId,
+} from '@/types/lend/index.js'
+
+/**
+ * Find a market config in an allowlist by address + chainId (case-insensitive on address).
+ * @description Shared between `BaseLendNamespace.getProviderForMarket` and
+ * `MorphoLendProvider._getPosition` to avoid duplicate match logic.
+ * @param allowlist - Optional list of allowed markets (undefined or empty → always returns undefined)
+ * @param marketId - Market identifier to look up
+ * @returns The matching market config, or undefined if not present
+ */
+export function findMarketInAllowlist(
+  allowlist: readonly LendMarketConfig[] | undefined,
+  marketId: LendMarketId,
+): LendMarketConfig | undefined {
+  if (!allowlist || allowlist.length === 0) return undefined
+  return allowlist.find(
+    (m) =>
+      m.address.toLowerCase() === marketId.address.toLowerCase() &&
+      m.chainId === marketId.chainId,
+  )
+}
+
+/**
+ * Validates that an asset matches the market's asset
+ * @param market - Market information
+ * @param asset - Asset to validate
+ * @throws Error if asset doesn't match the market's asset
+ */
+export function validateMarketAsset(market: LendMarket, asset: Asset): void {
+  if (!isMarketAsset(market, asset)) {
+    const marketAssetAddress =
+      market.asset.address[market.marketId.chainId as SupportedChainId]
+    const providedAssetAddress =
+      asset.address[market.marketId.chainId as SupportedChainId]
+    throw new MarketNotAllowedError({
+      address: market.marketId.address,
+      chainId: market.marketId.chainId,
+      reason: `Asset mismatch: provided ${providedAssetAddress} but market ${market.marketId.address} uses ${marketAssetAddress}`,
+    })
+  }
+}
+
+/**
+ * Checks if an asset matches the market's asset
+ * @param market - Market information
+ * @param asset - Asset to check
+ * @returns true if asset matches market's asset, false otherwise
+ */
+export function isMarketAsset(market: LendMarket, asset: Asset): boolean {
+  const marketAssetAddress =
+    market.asset.address[market.marketId.chainId as SupportedChainId]
+  const providedAssetAddress =
+    asset.address[market.marketId.chainId as SupportedChainId]
+  return marketAssetAddress === providedAssetAddress
+}

package/src/actions/shared/BaseNamespace.ts

@@ -0,0 +1,46 @@
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+
+/**
+ * Minimum contract a concrete provider must expose for `BaseNamespace` to
+ * aggregate it. Domain providers (LendProvider, SwapProvider, BorrowProvider)
+ * implement this plus their domain-specific surface.
+ */
+export interface NamespaceProvider {
+  supportedChainIds(): readonly SupportedChainId[]
+}
+
+/**
+ * Shared base for per-domain namespaces (Lend, Swap, Borrow, …).
+ * @description Holds the generic `providers` registry and exposes
+ * provider-enumeration + chain-union helpers every domain's namespace needs.
+ * Domain-specific routing and read operations live on the concrete
+ * `BaseXxxNamespace` subclass.
+ */
+export abstract class BaseNamespace<
+  TProvider extends NamespaceProvider,
+  TProviders extends Record<string, TProvider | undefined>,
+> {
+  constructor(protected readonly providers: TProviders) {}
+
+  /**
+   * Union of chain IDs supported by any configured provider.
+   */
+  supportedChainIds(): readonly SupportedChainId[] {
+    const chainIds = new Set<SupportedChainId>()
+    for (const provider of this.getAllProviders()) {
+      for (const chainId of provider.supportedChainIds()) {
+        chainIds.add(chainId)
+      }
+    }
+    return [...chainIds]
+  }
+
+  /**
+   * Enumerate every configured (non-undefined) provider.
+   */
+  protected getAllProviders(): TProvider[] {
+    return Object.values(this.providers).filter(
+      (p): p is TProvider => p !== undefined,
+    )
+  }
+}

package/src/actions/shared/__tests__/BaseNamespace.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  BaseNamespace,
+  type NamespaceProvider,
+} from '@/actions/shared/BaseNamespace.js'
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+
+class FakeProvider implements NamespaceProvider {
+  constructor(private readonly chains: readonly SupportedChainId[]) {}
+  supportedChainIds(): readonly SupportedChainId[] {
+    return this.chains
+  }
+}
+
+type FakeProviders = {
+  morpho?: FakeProvider
+  aave?: FakeProvider
+}
+
+class TestNamespace extends BaseNamespace<FakeProvider, FakeProviders> {
+  providersSnapshot(): FakeProvider[] {
+    return this.getAllProviders()
+  }
+}
+
+describe('BaseNamespace', () => {
+  it('returns only configured providers (skips undefined)', () => {
+    const morpho = new FakeProvider([1, 10])
+    const ns = new TestNamespace({ morpho, aave: undefined })
+
+    expect(ns.providersSnapshot()).toEqual([morpho])
+  })
+
+  it('returns all providers when multiple are configured', () => {
+    const morpho = new FakeProvider([1])
+    const aave = new FakeProvider([10])
+    const ns = new TestNamespace({ morpho, aave })
+
+    expect(ns.providersSnapshot()).toEqual([morpho, aave])
+  })
+
+  it('returns empty array when no providers are configured', () => {
+    const ns = new TestNamespace({})
+    expect(ns.providersSnapshot()).toEqual([])
+    expect(ns.supportedChainIds()).toEqual([])
+  })
+
+  it('unions supported chain ids across providers, deduplicated', () => {
+    const morpho = new FakeProvider([1, 10, 8453])
+    const aave = new FakeProvider([10, 8453, 42220])
+    const ns = new TestNamespace({ morpho, aave })
+
+    expect([...ns.supportedChainIds()].sort((a, b) => a - b)).toEqual([
+      1, 10, 8453, 42220,
+    ])
+  })
+})

package/src/{lend/providers → actions/shared}/morpho/contracts.ts

@@ -10,11 +10,11 @@ import {
   worldchain,
 } from 'viem/chains'
 
-import type { SupportedChainId } from '@/constants/supportedChains.js'
 import type {
   MorphoContracts,
   MorphoContractsRegistry,
-} from '@/types/lend/contracts.js'
+} from '@/actions/shared/morpho/types.js'
+import type { SupportedChainId } from '@/constants/supportedChains.js'
 
 /**
  * Morpho Blue core contract - same address on all chains via CREATE2

package/src/{swap → actions/swap}/__mocks__/MockSwapProvider.ts

@@ -1,10 +1,10 @@
 import type { Address } from 'viem'
 import { type MockedFunction, vi } from 'vitest'
 
+import { SwapProvider } from '@/actions/swap/core/SwapProvider.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
 import { MockChainManager } from '@/services/__mocks__/MockChainManager.js'
 import type { ChainManager } from '@/services/ChainManager.js'
-import { SwapProvider } from '@/swap/core/SwapProvider.js'
 import type { SwapSettings } from '@/types/actions.js'
 import type { Asset } from '@/types/asset.js'
 import type {
@@ -110,6 +110,10 @@ export class MockSwapProvider extends SwapProvider<SwapProviderConfig> {
     return this.validateMarketAllowed(assetIn, assetOut, chainId)
   }
 
+  public testBuildSwapTransactions(quote: SwapQuote): Promise<SwapTransaction> {
+    return this.buildSwapTransactions(quote)
+  }
+
   protected async _execute(
     params: ResolvedSwapParams,
   ): Promise<SwapTransaction> {
@@ -202,7 +206,7 @@ export class MockSwapProvider extends SwapProvider<SwapProviderConfig> {
       quotedAt: now,
       expiresAt: deadline,
       gasEstimate: 150000n,
-      quotedRecipient: (params.recipient ??
+      recipient: (params.recipient ??
         '0x0000000000000000000000000000000000000001') as Address,
     }
   }

package/src/{swap → actions/swap}/core/SwapProvider.ts

@@ -1,15 +1,20 @@
 import type { Address } from 'viem'
 import { formatUnits } from 'viem'
 
+import { UNIVERSAL_ROUTER_MSG_SENDER } from '@/actions/swap/core/markets.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
 import { ACTIONS_SUPPORTED_CHAIN_IDS } from '@/constants/supportedChains.js'
+import {
+  MarketNotAllowedError,
+  ProviderNotConfiguredError,
+  QuoteExpiredError,
+} from '@/core/error/errors.js'
+import type { ChainManager } from '@/services/ChainManager.js'
 import type {
   SwapExecuteParamsResolved,
   SwapQuoteParamsResolved,
-} from '@/ens/types.js'
-import type { ChainManager } from '@/services/ChainManager.js'
-import { UNIVERSAL_ROUTER_MSG_SENDER } from '@/swap/core/markets.js'
-import type { SwapSettings } from '@/types/actions.js'
+} from '@/services/nameservices/ens/types.js'
+import type { ApprovalMode, SwapSettings } from '@/types/actions.js'
 import type { Asset } from '@/types/asset.js'
 import type {
   GetSwapMarketParams,
@@ -29,6 +34,9 @@ import {
   buildTokenApprovalTx,
   checkPermit2Allowance,
   checkTokenAllowance,
+  resolveApprovalMode,
+  resolveErc20ApprovalAmount,
+  resolvePermit2ApprovalAmount,
 } from '@/utils/approve.js'
 import {
   getAssetAddress,
@@ -75,7 +83,7 @@ export abstract class SwapProvider<
   protected readonly _settings: SwapSettings
   protected readonly chainManager: ChainManager
 
-  constructor(
+  protected constructor(
     config: TConfig,
     chainManager: ChainManager,
     settings?: SwapSettings,
@@ -135,9 +143,20 @@ export abstract class SwapProvider<
   async execute(
     params: SwapExecuteParamsResolved | SwapQuote,
   ): Promise<SwapTransaction> {
+    // Resolve approval mode once at entry; the resolved value is set back on
+    // the params object so all downstream methods read a single populated field.
+    const resolvedApprovalMode = resolveApprovalMode(
+      params.approvalMode,
+      this._config.approvalMode,
+      this._settings.approvalMode,
+    )
+
     if (QUOTE_DISCRIMINATOR in params) {
       this.validateSwapExecute(params)
-      return this.executeFromQuote(params)
+      return this.executeFromQuote({
+        ...params,
+        approvalMode: resolvedApprovalMode,
+      })
     }
 
     this.validateSwapExecute(params)
@@ -145,7 +164,9 @@ export abstract class SwapProvider<
     // Raw params only
     validateNotBothAmounts(params.amountIn, params.amountOut)
     validateNotZeroAddress(params.walletAddress, 'walletAddress')
-    return this._execute(this.resolveParams(params))
+    return this._execute(
+      this.resolveParams({ ...params, approvalMode: resolvedApprovalMode }),
+    )
   }
 
   /**
@@ -246,9 +267,12 @@ export abstract class SwapProvider<
         marketBlocklist,
       )
       if (isBlocked) {
-        throw new Error(
-          `Pair ${assetIn.metadata.symbol}/${assetOut.metadata.symbol} is blocked on chain ${chainId}`,
-        )
+        throw new MarketNotAllowedError({
+          assetInSymbol: assetIn.metadata.symbol,
+          assetOutSymbol: assetOut.metadata.symbol,
+          chainId,
+          reason: 'Pair is blocked',
+        })
       }
     }
 
@@ -260,9 +284,12 @@ export abstract class SwapProvider<
         marketAllowlist,
       )
       if (!isAllowed) {
-        throw new Error(
-          `Pair ${assetIn.metadata.symbol}/${assetOut.metadata.symbol} is not in the allowlist for chain ${chainId}`,
-        )
+        throw new MarketNotAllowedError({
+          assetInSymbol: assetIn.metadata.symbol,
+          assetOutSymbol: assetOut.metadata.symbol,
+          chainId,
+          reason: 'Pair is not in the allowlist',
+        })
       }
     }
   }
@@ -309,9 +336,10 @@ export abstract class SwapProvider<
   ): SwapMarketConfig | undefined {
     const { marketAllowlist } = this._config
     if (!marketAllowlist?.length) {
-      throw new Error(
-        'No markets configured. Provide a marketAllowlist in swap provider config.',
-      )
+      throw new ProviderNotConfiguredError({
+        provider: 'marketAllowlist',
+        details: 'Provide a marketAllowlist in swap provider config.',
+      })
     }
     return this.findMatchingConfig(assetIn, assetOut, chainId, marketAllowlist)
   }
@@ -320,7 +348,16 @@ export abstract class SwapProvider<
    * Build Permit2 approval transactions for an ERC20 swap input.
    * Skipped for native assets. Checks both ERC20→Permit2 and Permit2→spender allowances in parallel.
    * Uses the resolved `permit2ExpirationSeconds` from provider → global → default.
-   * @param params - Resolved swap params (wallet address, asset info, chain)
+   *
+   * Approval amounts honour `params.approvalMode`:
+   * - `"exact"` approves only `requiredAmount` for both the outer ERC-20→Permit2
+   * allowance and the inner Permit2→spender allowance. Each subsequent swap
+   * needs its own approval transaction.
+   * - `"max"` approves `maxUint256` for the outer ERC-20 allowance and
+   * `maxUint160` (Permit2's allowance type) for the inner Permit2 allowance.
+   * Subsequent swaps within the expiration window skip the re-approval round
+   * trip entirely.
+   * @param params - Resolved swap params (wallet address, asset info, chain, approvalMode)
    * @param requiredAmount - Amount as raw bigint that must be approved
    * @param permit2Address - Permit2 contract address
    * @param permit2Spender - The router/contract that Permit2 should approve (e.g. Universal Router)
@@ -359,7 +396,11 @@ export abstract class SwapProvider<
 
     const tokenApproval =
       tokenAllowance < requiredAmount
-        ? buildTokenApprovalTx(token, permit2Address)
+        ? buildTokenApprovalTx(
+            token,
+            permit2Address,
+            resolveErc20ApprovalAmount(params.approvalMode, requiredAmount),
+          )
         : undefined
 
     // Permit2 expiration is in Unix seconds (matching EVM block.timestamp)
@@ -371,7 +412,10 @@ export abstract class SwapProvider<
             permit2Address,
             token,
             spender: permit2Spender,
-            amount: requiredAmount,
+            amount: resolvePermit2ApprovalAmount(
+              params.approvalMode,
+              requiredAmount,
+            ),
             expirySeconds: this.permit2ExpirationSeconds,
           })
         : undefined
@@ -380,13 +424,22 @@ export abstract class SwapProvider<
   }
 
   /**
-   * Build a SwapTransaction from a quote by fetching approvals and wrapping the swap calldata.
-   * Used by both the quote-execute path and provider _execute implementations.
-   * @param quote - SwapQuote with recipient set for allowance checks
+   * Build a SwapTransaction from a quote by fetching approvals and wrapping
+   * the swap calldata. Used by both the quote-execute path and provider
+   * `_execute` implementations. Quotes are required to have `recipient` set
+   * by the provider's `_getQuote`; sub-providers can dereference
+   * `quote.recipient` directly. Reads `quote.approvalMode` (populated by
+   * `execute()` at entry).
+   * @param quote - SwapQuote with recipient and approvalMode set
    */
   protected async buildSwapTransactions(
     quote: SwapQuote,
   ): Promise<SwapTransaction> {
+    if (!quote.recipient) {
+      throw new Error(
+        'SwapQuote.recipient missing — _getQuote must populate it',
+      )
+    }
     const approvals = await this._buildApprovals(quote)
 
     const swapTx: TransactionData = {
@@ -415,32 +468,6 @@ export abstract class SwapProvider<
   private async executeFromQuote(quote: SwapQuote): Promise<SwapTransaction> {
     this.validateQuoteExpiration(quote)
     validateNotZeroAddress(quote.execution.routerAddress, 'routerAddress')
-
-    if (!quote.recipient) {
-      throw new Error(
-        'SwapQuote.recipient is required for execution. Pass the quote through WalletSwapNamespace.execute() which injects the wallet address.',
-      )
-    }
-
-    // If the recipient changed since the quote was built (e.g. quote from
-    // ActionsSwapNamespace executed through WalletSwapNamespace), re-encode
-    // calldata with the correct recipient to prevent tokens going to the wrong address.
-    if (quote.recipient !== quote.quotedRecipient) {
-      const freshQuote = await this._getQuote({
-        assetIn: quote.assetIn,
-        assetOut: quote.assetOut,
-        amountIn: quote.amountIn,
-        chainId: quote.chainId,
-        slippage: quote.slippage,
-        deadline: quote.deadline,
-        recipient: quote.recipient,
-      })
-      return this.buildSwapTransactions({
-        ...freshQuote,
-        recipient: quote.recipient,
-      })
-    }
-
     return this.buildSwapTransactions(quote)
   }
 
@@ -454,19 +481,22 @@ export abstract class SwapProvider<
     validateAmountPositiveIfExists(params.amountIn)
     validateAmountPositiveIfExists(params.amountOut)
     validateSlippage(params.slippage ?? this.defaultSlippage, this.maxSlippage)
-    validateRecipient('recipient' in params ? params.recipient : undefined)
+    validateRecipient(params.recipient)
   }
 
   private validateQuoteExpiration(quote: SwapQuote): void {
     const now = Math.floor(Date.now() / 1000)
     if (now >= quote.expiresAt) {
-      throw new Error(
-        `Quote expired at ${quote.expiresAt}, current time is ${now}`,
-      )
+      throw new QuoteExpiredError({
+        expiresAt: quote.expiresAt,
+        currentTime: now,
+      })
     }
   }
 
-  private resolveParams(params: SwapExecuteParamsResolved): ResolvedSwapParams {
+  private resolveParams(
+    params: SwapExecuteParamsResolved & { approvalMode: ApprovalMode },
+  ): ResolvedSwapParams {
     return {
       amountInRaw: parseAssetAmount(params.assetIn, params.amountIn),
       amountOutRaw: parseAssetAmount(params.assetOut, params.amountOut),
@@ -480,6 +510,7 @@ export abstract class SwapProvider<
       recipient: params.recipient ?? params.walletAddress,
       walletAddress: params.walletAddress,
       chainId: params.chainId,
+      approvalMode: params.approvalMode,
     }
   }
 
@@ -560,8 +591,10 @@ export abstract class SwapProvider<
 
   /**
    * Build provider-specific approval transactions for a swap.
-   * Called by the base class during executeFromQuote with a validated recipient.
-   * @param quote - SwapQuote with recipient set to the real wallet address
+   * Called by the base class during executeFromQuote with a validated
+   * recipient and resolved approvalMode. Implementations read
+   * `quote.approvalMode` to choose between exact and max approvals.
+   * @param quote - SwapQuote with recipient set by the provider's _getQuote and approvalMode populated by execute() at entry
    * @returns Approval transactions needed before the swap (tokenApproval, permit2Approval)
    */
   protected abstract _buildApprovals(

package/src/{swap → actions/swap}/core/__tests__/SwapProvider.test.ts

@@ -1,8 +1,8 @@
 import type { Address } from 'viem'
 import { describe, expect, it } from 'vitest'
 
+import { MockSwapProvider } from '@/actions/swap/__mocks__/MockSwapProvider.js'
 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'
 
@@ -225,6 +225,56 @@ describe('SwapProvider', () => {
     })
   })
 
+  describe('buildSwapTransactions()', () => {
+    it('passes quote.recipient through to _buildApprovals', async () => {
+      const provider = new MockSwapProvider()
+      const customRecipient =
+        '0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB' as Address
+      const quote = await provider.getQuote({
+        assetIn: MockUSDC,
+        assetOut: MockWETH,
+        amountIn: 100,
+        chainId: 84532 as SupportedChainId,
+        recipient: customRecipient,
+      })
+      expect(quote.recipient).toBe(customRecipient)
+
+      await provider.testBuildSwapTransactions(quote)
+
+      expect(provider.mockBuildApprovals).toHaveBeenCalledWith(
+        expect.objectContaining({ recipient: customRecipient }),
+      )
+    })
+
+    it('defaults quote.recipient to UNIVERSAL_ROUTER_MSG_SENDER when no recipient is provided', async () => {
+      const provider = new MockSwapProvider()
+      const quote = await provider.getQuote({
+        assetIn: MockUSDC,
+        assetOut: MockWETH,
+        amountIn: 100,
+        chainId: 84532 as SupportedChainId,
+      })
+      expect(quote.recipient).toBe('0x0000000000000000000000000000000000000001')
+    })
+
+    it('throws if quote.recipient is missing (chokepoint guard)', async () => {
+      const provider = new MockSwapProvider()
+      const quote = await provider.getQuote({
+        assetIn: MockUSDC,
+        assetOut: MockWETH,
+        amountIn: 100,
+        chainId: 84532 as SupportedChainId,
+      })
+
+      // Simulate a faulty _getQuote by stripping recipient. The base guard
+      // should fire before _buildApprovals.
+      const { recipient: _recipient, ...rest } = quote
+      await expect(
+        provider.testBuildSwapTransactions(rest as typeof quote),
+      ).rejects.toThrow(/recipient missing/)
+    })
+  })
+
   describe('getQuote()', () => {
     it('should throw if chain not supported', async () => {
       const provider = new MockSwapProvider()

package/src/{swap → actions/swap}/core/markets.ts

@@ -1,6 +1,7 @@
 import type { Address } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { MarketNotFoundError } from '@/core/error/errors.js'
 import type { Asset } from '@/types/asset.js'
 import type {
   GetSwapMarketsParams,
@@ -69,7 +70,7 @@ export function findMarket<T extends SwapMarketConfig>(
     )
     if (match) return match
   }
-  throw new Error(`Market with poolId ${poolId} not found on chain ${chainId}`)
+  throw new MarketNotFoundError({ chainId, poolId })
 }
 
 /**

package/src/actions/swap/index.ts

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