@eth-optimism/actions-sdk 0.4.0 → 0.6.0

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

@@ -1,11 +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 { UNIVERSAL_ROUTER_MSG_SENDER } from '@/swap/core/markets.js'
-import type { SwapSettings } from '@/types/actions.js'
+import type {
+  SwapExecuteParamsResolved,
+  SwapQuoteParamsResolved,
+} from '@/services/nameservices/ens/types.js'
+import type { ApprovalMode, SwapSettings } from '@/types/actions.js'
 import type { Asset } from '@/types/asset.js'
 import type {
   GetSwapMarketParams,
@@ -16,7 +25,6 @@ import type {
   SwapMarketConfig,
   SwapProviderConfig,
   SwapQuote,
-  SwapQuoteParams,
   SwapTransaction,
   SwapTransactionData,
 } from '@/types/swap/index.js'
@@ -26,6 +34,9 @@ import {
   buildTokenApprovalTx,
   checkPermit2Allowance,
   checkTokenAllowance,
+  resolveApprovalMode,
+  resolveErc20ApprovalAmount,
+  resolvePermit2ApprovalAmount,
 } from '@/utils/approve.js'
 import {
   getAssetAddress,
@@ -40,6 +51,7 @@ import {
   validateNotBothAmounts,
   validateNotSameAsset,
   validateNotZeroAddress,
+  validateRecipient,
   validateSlippage,
 } from '@/utils/validation.js'
 
@@ -71,7 +83,7 @@ export abstract class SwapProvider<
   protected readonly _settings: SwapSettings
   protected readonly chainManager: ChainManager
 
-  constructor(
+  protected constructor(
     config: TConfig,
     chainManager: ChainManager,
     settings?: SwapSettings,
@@ -129,18 +141,32 @@ export abstract class SwapProvider<
    * @returns Transaction data ready for wallet execution
    */
   async execute(
-    params: SwapExecuteParams | SwapQuote,
+    params: SwapExecuteParamsResolved | SwapQuote,
   ): Promise<SwapTransaction> {
-    this.validateSwapExecute(params)
+    // 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) {
-      return this.executeFromQuote(params)
+      this.validateSwapExecute(params)
+      return this.executeFromQuote({
+        ...params,
+        approvalMode: resolvedApprovalMode,
+      })
     }
 
+    this.validateSwapExecute(params)
+
     // 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 }),
+    )
   }
 
   /**
@@ -149,7 +175,7 @@ export abstract class SwapProvider<
    * @param params - Quote parameters (assets, amounts, chain, slippage)
    * @returns SwapQuote with pricing, amounts, and pre-encoded calldata
    */
-  async getQuote(params: SwapQuoteParams): Promise<SwapQuote> {
+  async getQuote(params: SwapQuoteParamsResolved): Promise<SwapQuote> {
     validateChainSupported(params.chainId, this.supportedChainIds())
     return this._getQuote(params)
   }
@@ -241,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',
+        })
       }
     }
 
@@ -255,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',
+        })
       }
     }
   }
@@ -267,7 +299,7 @@ export abstract class SwapProvider<
    * @param params - Raw quote params from the user
    * @returns Resolved slippage, deadline, recipient, amountInRaw, and current timestamp
    */
-  protected resolveQuoteDefaults(params: SwapQuoteParams) {
+  protected resolveQuoteDefaults(params: SwapQuoteParamsResolved) {
     const slippage = params.slippage ?? this.defaultSlippage
     const now = Math.floor(Date.now() / 1000)
     const deadline = params.deadline ?? now + this.quoteExpirationSeconds
@@ -304,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)
   }
@@ -315,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)
@@ -354,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)
@@ -366,7 +412,10 @@ export abstract class SwapProvider<
             permit2Address,
             token,
             spender: permit2Spender,
-            amount: requiredAmount,
+            amount: resolvePermit2ApprovalAmount(
+              params.approvalMode,
+              requiredAmount,
+            ),
             expirySeconds: this.permit2ExpirationSeconds,
           })
         : undefined
@@ -375,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 = {
@@ -410,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)
   }
 
@@ -449,25 +481,22 @@ export abstract class SwapProvider<
     validateAmountPositiveIfExists(params.amountIn)
     validateAmountPositiveIfExists(params.amountOut)
     validateSlippage(params.slippage ?? this.defaultSlippage, this.maxSlippage)
-    this.validateRecipient(params)
-  }
-
-  private validateRecipient(params: SwapExecuteParams | SwapQuote): void {
-    if ('recipient' in params && params.recipient) {
-      validateNotZeroAddress(params.recipient, 'recipient')
-    }
+    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: SwapExecuteParams): ResolvedSwapParams {
+  private resolveParams(
+    params: SwapExecuteParamsResolved & { approvalMode: ApprovalMode },
+  ): ResolvedSwapParams {
     return {
       amountInRaw: parseAssetAmount(params.assetIn, params.amountIn),
       amountOutRaw: parseAssetAmount(params.assetOut, params.amountOut),
@@ -481,6 +510,7 @@ export abstract class SwapProvider<
       recipient: params.recipient ?? params.walletAddress,
       walletAddress: params.walletAddress,
       chainId: params.chainId,
+      approvalMode: params.approvalMode,
     }
   }
 
@@ -555,12 +585,16 @@ export abstract class SwapProvider<
     params: ResolvedSwapParams,
   ): Promise<SwapTransaction>
 
-  protected abstract _getQuote(params: SwapQuoteParams): Promise<SwapQuote>
+  protected abstract _getQuote(
+    params: SwapQuoteParamsResolved,
+  ): Promise<SwapQuote>
 
   /**
    * 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'

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).