@eth-optimism/actions-sdk 0.5.0 → 0.6.0

package/src/types/swap/base.ts

@@ -1,8 +1,8 @@
 import type { Address, Hex } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import type { EnsName } from '@/ens/types.js'
-import type { SwapProviderName } from '@/types/actions.js'
+import type { EnsName } from '@/services/nameservices/ens/types.js'
+import type { ApprovalMode, SwapProviderName } from '@/types/actions.js'
 import type { Asset } from '@/types/asset.js'
 import type { TransactionData } from '@/types/transaction.js'
 import type {
@@ -10,9 +10,9 @@ import type {
   TransactionReturnType,
 } from '@/wallet/core/wallets/abstract/types/index.js'
 
-export { SwapProvider } from '@/swap/core/SwapProvider.js'
-export { ActionsSwapNamespace } from '@/swap/namespaces/ActionsSwapNamespace.js'
-export { WalletSwapNamespace } from '@/swap/namespaces/WalletSwapNamespace.js'
+export { SwapProvider } from '@/actions/swap/core/SwapProvider.js'
+export { ActionsSwapNamespace } from '@/actions/swap/namespaces/ActionsSwapNamespace.js'
+export { WalletSwapNamespace } from '@/actions/swap/namespaces/WalletSwapNamespace.js'
 export type { SwapProviders } from '@/types/providers.js'
 
 /**
@@ -30,6 +30,8 @@ export interface SwapProviderConfig {
   marketAllowlist?: SwapMarketConfig[]
   /** Blocklist of swap markets to exclude */
   marketBlocklist?: SwapMarketConfig[]
+  /** Approval-amount strategy override for this provider. Overrides `SwapSettings.approvalMode`. */
+  approvalMode?: ApprovalMode
 }
 
 /**
@@ -93,6 +95,11 @@ export interface WalletSwapParams {
   recipient?: Address | EnsName
   /** Explicitly select a swap provider. Overrides routing config. */
   provider?: SwapProviderName
+  /**
+   * Override the wallet-level approval-amount strategy for this single swap.
+   * Falls back to `ActionsConfig.wallet.approvalMode` and finally to `"exact"`.
+   */
+  approvalMode?: ApprovalMode
 }
 
 /**
@@ -117,6 +124,8 @@ export interface ResolvedSwapParams {
   recipient: Address
   walletAddress: Address
   chainId: SupportedChainId
+  /** Resolved approval-amount strategy (per-call → wallet config → "exact"). */
+  approvalMode: ApprovalMode
 }
 
 /**
@@ -239,17 +248,20 @@ export interface SwapQuote {
   /** Estimated gas cost as raw bigint (native decimals) */
   gasEstimate?: bigint
   /**
-   * Wallet address that will execute this quote.
-   * Set by WalletSwapNamespace before execution — not available on price-only quotes.
-   * Used to check existing on-chain allowances and skip redundant approvals.
+   * Recipient address baked into execution.swapCalldata at quote time.
+   * Required. To execute a quote on a wallet, the quote must have been
+   * generated for that wallet (recipient === wallet.address); otherwise
+   * WalletSwapNamespace.execute throws. Re-quote via wallet.swap.getQuote
+   * when the executor differs from the quote's recipient.
    */
-  recipient?: Address
+  recipient: Address
   /**
-   * The recipient address baked into execution.swapCalldata at quote time.
-   * If recipient differs from quotedRecipient at execute time, calldata is re-encoded
-   * with the correct recipient to prevent tokens from being sent to the wrong address.
+   * Per-call override for the approval-amount strategy. When set, the provider
+   * uses this for the swap's approvals instead of the wallet-level config
+   * default. When unset, the provider falls back to the wallet's
+   * `approvalMode` config and finally to `"exact"`.
    */
-  quotedRecipient: Address
+  approvalMode?: ApprovalMode
 }
 
 /**

package/src/utils/{approve.test.ts → __tests__/approve.test.ts}

@@ -1,7 +1,8 @@
 import type { Address, PublicClient } from 'viem'
-import { decodeFunctionData } from 'viem'
+import { decodeFunctionData, maxUint160, maxUint256 } from 'viem'
 import { describe, expect, it, vi } from 'vitest'
 
+import { PERMIT2_ABI } from '@/utils/abi/permit2.js'
 import {
   buildApprovalTxIfNeeded,
   buildErc20ApprovalTx,
@@ -11,23 +12,11 @@ import {
   checkTokenAllowance,
   DEFAULT_PERMIT2_EXPIRY_SECONDS,
   getApprovalDeficit,
+  resolveApprovalMode,
+  resolveErc20ApprovalAmount,
+  resolvePermit2ApprovalAmount,
 } from '@/utils/approve.js'
 
-const PERMIT2_ABI = [
-  {
-    name: 'approve',
-    type: 'function',
-    stateMutability: 'nonpayable',
-    inputs: [
-      { name: 'token', type: 'address' },
-      { name: 'spender', type: 'address' },
-      { name: 'amount', type: 'uint160' },
-      { name: 'expiration', type: 'uint48' },
-    ],
-    outputs: [],
-  },
-] as const
-
 const TOKEN = '0x1111111111111111111111111111111111111111' as Address
 const OWNER = '0x2222222222222222222222222222222222222222' as Address
 const SPENDER = '0x3333333333333333333333333333333333333333' as Address
@@ -89,8 +78,8 @@ describe('checkTokenAllowance', () => {
 })
 
 describe('buildTokenApprovalTx', () => {
-  it('builds max approval to Permit2', () => {
-    const tx = buildTokenApprovalTx(TOKEN, PERMIT2)
+  it('builds approval to Permit2 for the given amount', () => {
+    const tx = buildTokenApprovalTx(TOKEN, PERMIT2, maxUint256)
 
     expect(tx.to).toBe(TOKEN)
     expect(tx.value).toBe(0n)
@@ -98,6 +87,50 @@ describe('buildTokenApprovalTx', () => {
     // Should encode approve(permit2, maxUint256)
     expect(tx.data.length).toBeGreaterThan(10)
   })
+
+  it('respects an exact-amount caller override', () => {
+    const tx = buildTokenApprovalTx(TOKEN, PERMIT2, 12345n)
+    expect(tx.to).toBe(TOKEN)
+    expect(tx.data).toMatch(/^0x/)
+  })
+})
+
+describe('resolveApprovalMode', () => {
+  it('prefers per-call when set', () => {
+    expect(resolveApprovalMode('max', 'exact', 'exact')).toBe('max')
+  })
+
+  it('falls through to provider default when per-call is undefined', () => {
+    expect(resolveApprovalMode(undefined, 'max', 'exact')).toBe('max')
+  })
+
+  it('falls through to global default when per-call and provider are undefined', () => {
+    expect(resolveApprovalMode(undefined, undefined, 'max')).toBe('max')
+  })
+
+  it('defaults to "exact" when nothing is set', () => {
+    expect(resolveApprovalMode(undefined, undefined, undefined)).toBe('exact')
+  })
+})
+
+describe('resolveErc20ApprovalAmount', () => {
+  it('returns required amount for "exact"', () => {
+    expect(resolveErc20ApprovalAmount('exact', 100n)).toBe(100n)
+  })
+
+  it('returns maxUint256 for "max"', () => {
+    expect(resolveErc20ApprovalAmount('max', 100n)).toBe(maxUint256)
+  })
+})
+
+describe('resolvePermit2ApprovalAmount', () => {
+  it('returns required amount for "exact"', () => {
+    expect(resolvePermit2ApprovalAmount('exact', 100n)).toBe(100n)
+  })
+
+  it('returns maxUint160 for "max" (Permit2 allowance is uint160-typed)', () => {
+    expect(resolvePermit2ApprovalAmount('max', 100n)).toBe(maxUint160)
+  })
 })
 
 describe('buildPermit2ApprovalTx', () => {

package/src/utils/__tests__/serializers.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import { serializeBigInt } from '@/utils/serializers.js'
+
+describe('serializeBigInt', () => {
+  it('coerces bigints to decimal strings', () => {
+    expect(serializeBigInt({ amount: 1n })).toEqual({ amount: '1' })
+  })
+
+  it('preserves precision for large bigints', () => {
+    const huge = 1234567890123456789n
+    expect(serializeBigInt({ n: huge })).toEqual({ n: '1234567890123456789' })
+  })
+
+  it('never emits scientific notation', () => {
+    const big = 10n ** 30n
+    expect(serializeBigInt({ n: big }).n).toBe(
+      '1000000000000000000000000000000',
+    )
+  })
+
+  it('recurses through arrays and nested objects', () => {
+    expect(
+      serializeBigInt({
+        balances: [
+          { chainId: 84532, amount: 100n },
+          { chainId: 10, amount: 200n },
+        ],
+      }),
+    ).toEqual({
+      balances: [
+        { chainId: 84532, amount: '100' },
+        { chainId: 10, amount: '200' },
+      ],
+    })
+  })
+
+  it('passes through non-bigint primitives untouched', () => {
+    expect(serializeBigInt({ s: 'hello', n: 42, b: true, z: null })).toEqual({
+      s: 'hello',
+      n: 42,
+      b: true,
+      z: null,
+    })
+  })
+
+  it('returns a fresh object (no shared references)', () => {
+    const input = { a: { b: 1n } }
+    const output = serializeBigInt(input)
+    expect(output).not.toBe(input)
+    expect(output.a).not.toBe(input.a)
+  })
+})

package/src/utils/{validateAddresses.test.ts → __tests__/validateAddresses.test.ts}

@@ -7,20 +7,20 @@ import {
   getMockAuthorizationContext,
 } from '@/__mocks__/MockPrivyClient.js'
 import { Actions } from '@/actions.js'
-import {
-  NATIVELY_SUPPORTED_ASSETS,
-  OP_DEMO,
-  USDC_DEMO,
-} from '@/constants/assets.js'
 import {
   POOL_ADDRESSES_MAINNET,
   POOL_ADDRESSES_TESTNET,
   WETH_GATEWAY_ADDRESSES_MAINNET,
   WETH_GATEWAY_ADDRESSES_TESTNET,
-} from '@/lend/providers/aave/addresses.js'
-import { MORPHO_CONTRACTS } from '@/lend/providers/morpho/contracts.js'
-import { UNISWAP_ADDRESSES } from '@/swap/providers/uniswap/addresses.js'
-import { VELODROME_CHAINS } from '@/swap/providers/velodrome/addresses.js'
+} from '@/actions/lend/providers/aave/addresses.js'
+import { MORPHO_CONTRACTS } from '@/actions/shared/morpho/contracts.js'
+import { UNISWAP_ADDRESSES } from '@/actions/swap/providers/uniswap/addresses.js'
+import { VELODROME_CHAINS } from '@/actions/swap/providers/velodrome/addresses.js'
+import {
+  NATIVELY_SUPPORTED_ASSETS,
+  OP_DEMO,
+  USDC_DEMO,
+} from '@/constants/assets.js'
 import type { Asset } from '@/types/asset.js'
 import type { LendMarketConfig } from '@/types/lend/index.js'
 import {

package/src/utils/abi/permit2.ts

@@ -0,0 +1,33 @@
+/**
+ * Permit2 ABI (subset for approvals).
+ * @see https://github.com/Uniswap/permit2
+ */
+export const PERMIT2_ABI = [
+  {
+    name: 'allowance',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [
+      { name: 'owner', type: 'address' },
+      { name: 'token', type: 'address' },
+      { name: 'spender', type: 'address' },
+    ],
+    outputs: [
+      { name: 'amount', type: 'uint160' },
+      { name: 'expiration', type: 'uint48' },
+      { name: 'nonce', type: 'uint48' },
+    ],
+  },
+  {
+    name: 'approve',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'token', type: 'address' },
+      { name: 'spender', type: 'address' },
+      { name: 'amount', type: 'uint160' },
+      { name: 'expiration', type: 'uint48' },
+    ],
+    outputs: [],
+  },
+] as const

package/src/utils/approve.ts

@@ -1,44 +1,13 @@
 import type { Address, PublicClient } from 'viem'
-import { encodeFunctionData, erc20Abi, maxUint256 } from 'viem'
+import { encodeFunctionData, erc20Abi, maxUint160, maxUint256 } from 'viem'
 
+import type { ApprovalMode } from '@/types/actions.js'
 import type { TransactionData } from '@/types/transaction.js'
+import { PERMIT2_ABI } from '@/utils/abi/permit2.js'
 
 /** Default Permit2 approval expiry: 30 days in seconds */
 export const DEFAULT_PERMIT2_EXPIRY_SECONDS = 30 * 24 * 60 * 60
 
-/**
- * Permit2 ABI (subset for approvals)
- */
-const PERMIT2_ABI = [
-  {
-    name: 'allowance',
-    type: 'function',
-    stateMutability: 'view',
-    inputs: [
-      { name: 'owner', type: 'address' },
-      { name: 'token', type: 'address' },
-      { name: 'spender', type: 'address' },
-    ],
-    outputs: [
-      { name: 'amount', type: 'uint160' },
-      { name: 'expiration', type: 'uint48' },
-      { name: 'nonce', type: 'uint48' },
-    ],
-  },
-  {
-    name: 'approve',
-    type: 'function',
-    stateMutability: 'nonpayable',
-    inputs: [
-      { name: 'token', type: 'address' },
-      { name: 'spender', type: 'address' },
-      { name: 'amount', type: 'uint160' },
-      { name: 'expiration', type: 'uint48' },
-    ],
-    outputs: [],
-  },
-] as const
-
 /**
  * Permit2 allowance info
  */
@@ -76,14 +45,56 @@ export async function checkPermit2Allowance(params: {
 
 /**
  * Build ERC20 token approval transaction to Permit2.
- * Uses maxUint256 — the Uniswap-canonical pattern.
- * Permit2 is immutable with no owner; spending is scoped by its own allowance system.
+ *
+ * Permit2 is immutable with no owner; in the canonical Uniswap pattern this
+ * approval is granted as `maxUint256` once and reused across many swaps.
+ * Callers can opt back into exact-amount approvals by passing the explicit
+ * `requiredAmount`, which trades the round-trip cost on every swap for a
+ * tighter on-chain allowance.
  */
 export function buildTokenApprovalTx(
   token: Address,
   permit2Address: Address,
+  amount: bigint,
 ): TransactionData {
-  return buildErc20ApprovalTx(token, permit2Address, maxUint256)
+  return buildErc20ApprovalTx(token, permit2Address, amount)
+}
+
+/**
+ * Resolve the effective {@link ApprovalMode} from the per-call → per-provider
+ * → shared-settings precedence chain, defaulting to `"exact"`. Mirrors how
+ * `defaultSlippage` resolves across the same layers.
+ */
+export function resolveApprovalMode(
+  perCall: ApprovalMode | undefined,
+  providerDefault: ApprovalMode | undefined,
+  globalDefault: ApprovalMode | undefined,
+): ApprovalMode {
+  return perCall ?? providerDefault ?? globalDefault ?? 'exact'
+}
+
+/**
+ * Pick an approval amount for an ERC-20 → spender allowance based on the
+ * caller's chosen {@link ApprovalMode}.
+ * @param mode `"exact"` returns `requiredAmount`; `"max"` returns `maxUint256`.
+ */
+export function resolveErc20ApprovalAmount(
+  mode: ApprovalMode,
+  requiredAmount: bigint,
+): bigint {
+  return mode === 'max' ? maxUint256 : requiredAmount
+}
+
+/**
+ * Pick an approval amount for Permit2's inner (token, spender) allowance —
+ * which is uint160-typed, not uint256.
+ * @param mode `"exact"` returns `requiredAmount`; `"max"` returns `maxUint160`.
+ */
+export function resolvePermit2ApprovalAmount(
+  mode: ApprovalMode,
+  requiredAmount: bigint,
+): bigint {
+  return mode === 'max' ? maxUint160 : requiredAmount
 }
 
 /**

package/src/utils/assets.ts

@@ -2,6 +2,10 @@ import type { Address } from 'viem'
 import { parseUnits } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
+import {
+  AssetNotSupportedOnChainError,
+  NativeAssetAddressError,
+} from '@/core/error/errors.js'
 import type { Asset } from '@/types/asset.js'
 
 /**
@@ -75,14 +79,10 @@ export function getAssetAddress(
 ): Address {
   const address = asset.address[chainId]
   if (!address) {
-    throw new Error(
-      `Asset ${asset.metadata.symbol} is not supported on chain ${chainId}`,
-    )
+    throw new AssetNotSupportedOnChainError(asset.metadata.symbol, chainId)
   }
   if (address === 'native') {
-    throw new Error(
-      `Asset ${asset.metadata.symbol} is a native asset and has no contract address.`,
-    )
+    throw new NativeAssetAddressError(asset.metadata.symbol)
   }
   return address
 }

package/src/utils/serializers.ts

@@ -0,0 +1,21 @@
+/**
+ * @description Deep-clones an object, replacing every `bigint` with its
+ * decimal string form. Needed because `JSON.stringify` throws on `bigint`
+ * but Actions SDK return types carry `bigint` amounts, balances, and ids.
+ *
+ * The returned object preserves the input type signature for ergonomics;
+ * `bigint` fields are strings at runtime and callers must treat them as
+ * such. Use only at serialization boundaries (HTTP responses, CLI stdout).
+ * @param obj - Value to clone. Objects, arrays, and primitives are
+ * supported; cycles, `Map`, `Set`, `Date`, and `undefined` follow standard
+ * `JSON.stringify` semantics.
+ * @returns A structurally identical clone with every `bigint` coerced to
+ * its base-10 string representation.
+ */
+export function serializeBigInt<T>(obj: T): T {
+  return JSON.parse(
+    JSON.stringify(obj, (_key, value) =>
+      typeof value === 'bigint' ? value.toString() : value,
+    ),
+  )
+}

package/src/utils/validation.ts

@@ -2,7 +2,19 @@ import type { Address } from 'viem'
 import { isAddress } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import type { Asset } from '@/types/asset.js'
+import {
+  AmountRequiredError,
+  AssetNotSupportedOnChainError,
+  ChainNotSupportedError,
+  ConflictingAmountsError,
+  InvalidAmountError,
+  InvalidParamsError,
+  SameAssetError,
+  SlippageOutOfRangeError,
+  ZeroAddressError,
+} from '@/core/error/errors.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { Asset, BalanceFetchOptions } from '@/types/asset.js'
 import { isAssetSupportedOnChain } from '@/utils/assets.js'
 
 const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'
@@ -12,13 +24,13 @@ export function validateAmountProvided(
   amountOut?: number,
 ): void {
   if (amountIn === undefined && amountOut === undefined) {
-    throw new Error('Either amountIn or amountOut must be provided')
+    throw new AmountRequiredError()
   }
 }
 
 export function validateAmountPositiveIfExists(amount?: number): void {
   if (amount !== undefined && amount <= 0) {
-    throw new Error('Amount must be positive')
+    throw new InvalidAmountError(amount)
   }
 }
 
@@ -27,7 +39,7 @@ export function validateNotBothAmounts(
   amountOut?: number,
 ): void {
   if (amountIn !== undefined && amountOut !== undefined) {
-    throw new Error('Provide either amountIn or amountOut, not both')
+    throw new ConflictingAmountsError()
   }
 }
 
@@ -36,21 +48,19 @@ export function validateNotSameAsset(assetIn: Asset, assetOut: Asset): void {
     assetIn.metadata.symbol.toLowerCase() ===
     assetOut.metadata.symbol.toLowerCase()
   ) {
-    throw new Error('Cannot swap an asset for itself')
+    throw new SameAssetError(assetIn.metadata.symbol)
   }
 }
 
 export function validateNotZeroAddress(address: Address, label: string): void {
   if (address === ZERO_ADDRESS) {
-    throw new Error(`${label} cannot be the zero address`)
+    throw new ZeroAddressError(label, address)
   }
 }
 
 export function validateSlippage(slippage: number, maxSlippage: number): void {
   if (slippage < 0 || slippage > maxSlippage) {
-    throw new Error(
-      `Slippage ${slippage} exceeds allowed range [0, ${maxSlippage * 100}%]`,
-    )
+    throw new SlippageOutOfRangeError(slippage, maxSlippage)
   }
 }
 
@@ -59,20 +69,37 @@ export function validateChainSupported(
   supportedChainIds: readonly number[],
 ): void {
   if (!supportedChainIds.includes(chainId)) {
-    throw new Error(
-      `Chain ${chainId} is not supported. Supported chains: ${supportedChainIds.join(', ')}`,
-    )
+    throw new ChainNotSupportedError({ chainId, supportedChainIds })
   }
 }
 
+/**
+ * Guard for `BalanceFetchOptions` — verifies a caller-supplied `chainIds` filter is non-empty and each id is a member of `chainManager.getSupportedChains()`. No-op when `chainIds` is omitted.
+ * @throws InvalidParamsError when `chainIds` is `[]`.
+ * @throws ChainNotSupportedError when any id is not configured on the manager.
+ */
+export function validateBalanceFetchOptions(
+  options: BalanceFetchOptions | undefined,
+  chainManager: ChainManager,
+): void {
+  if (options?.chainIds === undefined) return
+  if (options.chainIds.length === 0) {
+    throw new InvalidParamsError({
+      param: 'chainIds',
+      expected: 'SupportedChainId[] (non-empty)',
+      received: '[]',
+    })
+  }
+  const supported = chainManager.getSupportedChains()
+  for (const id of options.chainIds) validateChainSupported(id, supported)
+}
+
 export function validateAssetOnChain(
   asset: Asset,
   chainId: SupportedChainId,
 ): void {
   if (!isAssetSupportedOnChain(asset, chainId)) {
-    throw new Error(
-      `Asset ${asset.metadata.symbol} not supported on chain ${chainId}`,
-    )
+    throw new AssetNotSupportedOnChainError(asset.metadata.symbol, chainId)
   }
 }
 

package/src/wallet/core/error/errors.ts

@@ -0,0 +1,30 @@
+import type { TransactionReceipt } from 'viem'
+
+import { ActionsError } from '@/core/error/errors.js'
+
+/**
+ * Error for a transaction that was included on-chain but reverted
+ * @description Thrown when a transaction makes it into a block (i.e. has a
+ * confirmed receipt) yet the EVM execution failed. The full
+ * {@link TransactionReceipt | transaction receipt} is attached for
+ * post-mortem analysis (status, logs, gas usage, etc.).
+ */
+export class TransactionConfirmedButRevertedError extends ActionsError {
+  override name = 'TransactionConfirmedButRevertedError' as const
+  /** Full receipt returned by the node for the reverted transaction */
+  receipt: TransactionReceipt
+
+  /**
+   * Create an instance of TransactionConfirmedButRevertedError
+   * @param message - Human-readable description of the failure
+   * @param receipt - Confirmed transaction receipt indicating a revert
+   */
+  constructor(message: string, receipt: TransactionReceipt) {
+    if (!message || typeof message !== 'string') {
+      throw new Error('"message" must be a nonempty string.')
+    }
+
+    super(message, { metaMessages: [`txHash: ${receipt.transactionHash}`] })
+    this.receipt = receipt
+  }
+}