@eth-optimism/actions-sdk 0.5.0 → 0.7.0

package/src/types/lend/base.ts

@@ -1,8 +1,12 @@
 import type { Address } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import type { LendProviderName } from '@/types/actions.js'
+import type { ApprovalMode, LendProviderName } from '@/types/actions.js'
 import type { Asset } from '@/types/asset.js'
+import type {
+  FilterAssetChain,
+  TransactionOptions,
+} from '@/types/common/index.js'
 // Import and re-export shared transaction type for backwards compatibility
 import type { TransactionData } from '@/types/transaction.js'
 import type {
@@ -10,9 +14,9 @@ import type {
   TransactionReturnType,
 } from '@/wallet/core/wallets/abstract/types/index.js'
 
-export { LendProvider } from '@/lend/core/LendProvider.js'
-export { ActionsLendNamespace } from '@/lend/namespaces/ActionsLendNamespace.js'
-export { WalletLendNamespace } from '@/lend/namespaces/WalletLendNamespace.js'
+export { LendProvider } from '@/actions/lend/core/LendProvider.js'
+export { ActionsLendNamespace } from '@/actions/lend/namespaces/ActionsLendNamespace.js'
+export { WalletLendNamespace } from '@/actions/lend/namespaces/WalletLendNamespace.js'
 export type { TransactionData }
 
 /**
@@ -68,8 +72,8 @@ export interface LendTransaction {
   hash?: string
   /** Amount lent */
   amount: bigint
-  /** Asset address */
-  asset: Address
+  /** Underlying ERC-20 address (the wrapped form for native deposits) */
+  assetAddress: Address
   /** Market ID */
   marketId: string
   /** Estimated APY at time of lending */
@@ -186,19 +190,6 @@ export interface LendMarket {
   metadata: LendMarketMetadata
 }
 
-/**
- * Lending options
- * @description Configuration options for lending operations
- */
-export interface LendOptions {
-  /** Deadline for transaction (timestamp) */
-  deadline?: number
-  /** Gas limit override */
-  gasLimit?: bigint
-  /** Gas price override */
-  gasPrice?: bigint
-}
-
 /**
  * Individual lending provider configuration
  * @description Configuration for a single lending provider
@@ -208,6 +199,8 @@ export interface LendProviderConfig {
   marketAllowlist?: LendMarketConfig[]
   /** Blocklist of markets to exclude from lending */
   marketBlocklist?: LendMarketConfig[]
+  /** Approval-amount strategy override for this provider. Overrides `LendSettings.approvalMode`. */
+  approvalMode?: ApprovalMode
 }
 
 /**
@@ -238,7 +231,12 @@ export interface LendOpenPositionBaseParams {
   /** Wallet address for receiving shares and as owner (auto-populated by WalletLendNamespace) */
   walletAddress?: Address
   /** Optional lending configuration */
-  options?: LendOptions
+  options?: TransactionOptions
+  /**
+   * Override the wallet-level approval-amount strategy for this single supply.
+   * Falls back to `ActionsConfig.wallet.approvalMode` and finally to `"exact"`.
+   */
+  approvalMode?: ApprovalMode
 }
 
 /**
@@ -255,7 +253,7 @@ export interface LendOpenPositionParams extends LendOpenPositionBaseParams {
  */
 export interface LendOpenPositionInternalParams extends Omit<
   LendOpenPositionBaseParams,
-  'walletAddress'
+  'walletAddress' | 'approvalMode'
 > {
   /** Amount to lend in wei */
   amountWei: bigint
@@ -263,6 +261,31 @@ export interface LendOpenPositionInternalParams extends Omit<
   walletAddress: Address
 }
 
+/**
+ * Provider-supplied description of a lend open-position operation. The base
+ * `LendProvider` consumes this to build the surrounding `LendTransaction`,
+ * including the ERC-20 approval transaction (if any). Providers describe
+ * **what** the deposit looks like; the base derives **how** the approval is
+ * built from `params.asset` (native vs. ERC-20).
+ *
+ * For native-asset deposits, omit `spender` — the base reads `params.asset.type`
+ * and skips approval construction entirely. For ERC-20 deposits, `spender` is
+ * required and the base will throw if it's missing.
+ */
+export interface LendOpenPosition {
+  /** Underlying ERC-20 address being deposited (the wrapped form for native deposits). */
+  assetAddress: Address
+  /**
+   * ERC-20 spender that needs allowance to pull `params.amountWei` from the
+   * wallet. Required for ERC-20 deposits; omit for native deposits.
+   */
+  spender?: Address
+  /** The deposit transaction itself (provider-specific calldata; `value` set for native). */
+  transaction: TransactionData
+  /** APY snapshot at the time the description was built. */
+  apy: number
+}
+
 /**
  * Parameters for withdraw operation (internal)
  * @description Internal parameters required for withdrawing assets
@@ -277,7 +300,7 @@ export interface LendClosePositionParams {
   /** Wallet address for receiving assets and as owner */
   walletAddress: Address
   /** Optional withdrawal configuration */
-  options?: LendOptions
+  options?: TransactionOptions
 }
 
 /**
@@ -294,7 +317,7 @@ export interface ClosePositionParams {
   /** Wallet address for receiving assets and as owner (auto-populated by WalletLendNamespace) */
   walletAddress?: Address
   /** Optional withdrawal configuration */
-  options?: LendOptions
+  options?: TransactionOptions
 }
 
 /**
@@ -308,17 +331,6 @@ export interface GetPositionParams {
   asset?: Asset
 }
 
-/**
- * Common filter parameters for asset and chain
- * @description Base interface for filtering by asset and/or chain
- */
-export interface FilterAssetChain {
-  /** Optional asset to filter by */
-  asset?: Asset
-  /** Optional chain ID to filter by */
-  chainId?: SupportedChainId
-}
-
 /**
  * Parameters for getting lending markets
  * @description Parameters for filtering lending markets
@@ -347,11 +359,11 @@ export interface LendProviderMethods {
   /**
    * Provider implementation of openPosition method
    * @param params - Open position operation parameters
-   * @returns Promise resolving to transaction data
+   * @returns Promise resolving to a `LendOpenPosition` description
    */
   _openPosition(
     params: LendOpenPositionInternalParams,
-  ): Promise<TransactionData>
+  ): Promise<LendOpenPosition>
 
   /**
    * Provider implementation of closePosition method

package/src/types/lend/index.ts

@@ -1,3 +1,2 @@
 export * from '@/types/lend/base.js'
-export * from '@/types/lend/contracts.js'
 export * from '@/types/lend/morpho.js'

package/src/types/providers.ts

@@ -1,22 +1,40 @@
-import type { LendProvider } from '@/lend/core/LendProvider.js'
-import type { SwapProvider } from '@/swap/core/SwapProvider.js'
+import type { LendProvider } from '@/actions/lend/core/LendProvider.js'
+import type { SwapProvider } from '@/actions/swap/core/SwapProvider.js'
 import type { LendProviderConfig } from '@/types/lend/index.js'
 import type { SwapProviderConfig } from '@/types/swap/index.js'
 
+/**
+ * Runtime list of lend provider names. Source of truth for both the
+ * `LendProviderName` type union and any consumer (CLI, validators) that
+ * needs to enumerate provider names at runtime.
+ */
+export const LEND_PROVIDER_NAMES = ['morpho', 'aave'] as const
+
+/** Names of available lend providers. */
+export type LendProviderName = (typeof LEND_PROVIDER_NAMES)[number]
+
 /**
  * Map of available lend providers keyed by provider name.
- * Add new lend providers here — this is the single source of truth.
+ * Add new providers by extending `LEND_PROVIDER_NAMES`.
  */
 export type LendProviders = {
-  morpho?: LendProvider<LendProviderConfig>
-  aave?: LendProvider<LendProviderConfig>
+  [K in LendProviderName]?: LendProvider<LendProviderConfig>
 }
 
+/**
+ * Runtime list of swap provider names. Source of truth for both the
+ * `SwapProviderName` type union and any consumer (CLI, validators) that
+ * needs to enumerate provider names at runtime.
+ */
+export const SWAP_PROVIDER_NAMES = ['uniswap', 'velodrome'] as const
+
+/** Names of available swap providers. */
+export type SwapProviderName = (typeof SWAP_PROVIDER_NAMES)[number]
+
 /**
  * Map of available swap providers keyed by provider name.
- * Add new swap providers here — this is the single source of truth.
+ * Add new providers by extending `SWAP_PROVIDER_NAMES`.
  */
 export type SwapProviders = {
-  uniswap?: SwapProvider<SwapProviderConfig>
-  velodrome?: SwapProvider<SwapProviderConfig>
+  [K in SwapProviderName]?: SwapProvider<SwapProviderConfig>
 }

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__/lendConfig.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+
+import { MockUSDCAsset } from '@/__mocks__/MockAssets.js'
+import type { LendConfig } from '@/types/actions.js'
+import type { LendMarketConfig } from '@/types/lend/base.js'
+import { getLendMarketAllowlist } from '@/utils/lendConfig.js'
+
+const morphoMarket: LendMarketConfig = {
+  address: '0x0000000000000000000000000000000000000001',
+  chainId: 130,
+  name: 'Morpho USDC',
+  asset: MockUSDCAsset,
+  lendProvider: 'morpho',
+}
+
+const aaveMarket: LendMarketConfig = {
+  address: '0x0000000000000000000000000000000000000002',
+  chainId: 130,
+  name: 'Aave USDC',
+  asset: MockUSDCAsset,
+  lendProvider: 'aave',
+}
+
+describe('getLendMarketAllowlist', () => {
+  it('returns empty list when lend config is undefined', () => {
+    expect(getLendMarketAllowlist(undefined)).toEqual([])
+  })
+
+  it('flattens allowlists across all providers', () => {
+    const lend: LendConfig = {
+      morpho: { marketAllowlist: [morphoMarket] },
+      aave: { marketAllowlist: [aaveMarket] },
+    }
+    expect(getLendMarketAllowlist(lend)).toEqual([morphoMarket, aaveMarket])
+  })
+
+  it('skips the settings sibling key', () => {
+    const lend: LendConfig = {
+      morpho: { marketAllowlist: [morphoMarket] },
+      settings: { approvalMode: 'max' },
+    }
+    expect(getLendMarketAllowlist(lend)).toEqual([morphoMarket])
+  })
+
+  it('returns empty list when no provider declares an allowlist', () => {
+    const lend: LendConfig = {
+      morpho: {},
+      settings: { approvalMode: 'exact' },
+    }
+    expect(getLendMarketAllowlist(lend)).toEqual([])
+  })
+})

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
 }
 
 /**