@eth-optimism/actions-sdk 0.4.0 → 0.6.0

package/src/services/nameservices/ens/utils.ts

@@ -0,0 +1,85 @@
+import type { Address, PublicClient } from 'viem'
+import { isAddress, isAddressEqual, zeroAddress } from 'viem'
+import { normalize } from 'viem/ens'
+
+import {
+  EnsNotConfiguredError,
+  EnsResolutionError,
+  EnsRpcError,
+} from '@/services/nameservices/ens/errors.js'
+import type { EnsName } from '@/services/nameservices/ens/types.js'
+
+export { type EnsName, isEnsName } from '@/services/nameservices/ens/types.js'
+
+/** Resolves an ENS name or address to a checksummed hex Address, or returns undefined. */
+export type RecipientResolver = (
+  recipient: Address | EnsName | undefined,
+) => Promise<Address | undefined>
+
+/** Pass-through resolver used when no ENS resolution is configured. Throws on ENS names. */
+export const passthroughResolver: RecipientResolver = (r) => {
+  if (r !== undefined && !isAddress(r, { strict: false })) {
+    throw new Error(`ENS resolution is not configured; received "${r}"`)
+  }
+  return Promise.resolve(r as Address | undefined)
+}
+
+/**
+ * Low-level utility to resolve an ENS name or hex address to a checksummed hex address.
+ * Use this when you manage your own viem PublicClient (e.g. inside providers or scripts).
+ *
+ * If you have an {@link Actions} instance, prefer `actions.ens.getAddress()` instead —
+ * it handles client lookup and fallback automatically from your chain configuration.
+ *
+ * Hex addresses (0x...) are returned as-is after format validation.
+ * ENS names require a mainnet public client for on-chain resolution.
+ * @param input - Hex address (0x...) or ENS name (e.g. "vitalik.eth")
+ * @param mainnetClient - Public client connected to Ethereum mainnet (required for ENS names)
+ * @returns Resolved hex address
+ * @throws {EnsNotConfiguredError} If mainnet client is not provided
+ * @throws {EnsResolutionError} If the name is invalid or cannot be resolved
+ * @throws {EnsRpcError} If the RPC call fails
+ */
+export async function resolveAddress(
+  input: Address | EnsName,
+  mainnetClient?: PublicClient,
+): Promise<Address> {
+  if (isAddress(input, { strict: false })) return input
+
+  if (!mainnetClient) throw new EnsNotConfiguredError()
+
+  const normalized = (() => {
+    try {
+      return normalize(input)
+    } catch (cause) {
+      throw new EnsResolutionError(
+        `Invalid address or ENS name: "${input}"`,
+        input,
+        { cause },
+      )
+    }
+  })()
+
+  const resolved = await mainnetClient
+    .getEnsAddress({ name: normalized })
+    .catch((cause: unknown) => {
+      throw new EnsRpcError(
+        `ENS resolution failed for "${input}": RPC error`,
+        input,
+        { cause },
+      )
+    })
+
+  if (!resolved)
+    throw new EnsResolutionError(
+      `ENS name "${input}" could not be resolved`,
+      input,
+    )
+  if (isAddressEqual(resolved, zeroAddress)) {
+    throw new EnsResolutionError(
+      `ENS name "${input}" resolved to the zero address`,
+      input,
+    )
+  }
+  return resolved
+}

package/src/services/tokenBalance.ts

@@ -4,20 +4,24 @@ import { erc20Abi, formatEther, formatUnits } from 'viem'
 import { ETH } from '@/constants/assets.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
 import type { ChainManager } from '@/services/ChainManager.js'
-import type { Asset, TokenBalance } from '@/types/asset.js'
+import type { Asset, BalanceFetchOptions, TokenBalance } from '@/types/asset.js'
 
 /**
- * Fetch ETH balance across all supported chains
+ * Fetch ETH balance across the requested chains (or all supported chains).
  * @param chainManager - The chain manager
  * @param walletAddress - The wallet address
+ * @param options - Optional `chainIds` filter (caller-validated)
  * @returns Promise resolving to ETH balance
  */
 export async function fetchETHBalance(
   chainManager: ChainManager,
   walletAddress: Address,
+  options?: BalanceFetchOptions,
 ): Promise<TokenBalance> {
-  const supportedChains = chainManager.getSupportedChains()
-  const chainBalancePromises = supportedChains.map(async (chainId) => {
+  const targetChains = [
+    ...new Set(options?.chainIds ?? chainManager.getSupportedChains()),
+  ]
+  const chainBalancePromises = targetChains.map(async (chainId) => {
     const publicClient = chainManager.getPublicClient(chainId)
     const balanceRaw = await publicClient.getBalance({
       address: walletAddress,
@@ -48,15 +52,20 @@ export async function fetchETHBalance(
 }
 
 /**
- * Fetch total balance for this asset across all supported chains
+ * Fetch total balance for this asset across the requested chains (or all
+ * supported chains). Chains where the asset has no configured address are
+ * silently skipped, matching the unfiltered behavior.
  */
 export async function fetchERC20Balance(
   chainManager: ChainManager,
   walletAddress: Address,
   asset: Asset,
+  options?: BalanceFetchOptions,
 ): Promise<TokenBalance> {
-  const supportedChains = chainManager.getSupportedChains()
-  const chainsWithToken = supportedChains.filter(
+  const targetChains = [
+    ...new Set(options?.chainIds ?? chainManager.getSupportedChains()),
+  ]
+  const chainsWithToken = targetChains.filter(
     (chainId) => asset.address[chainId],
   )
 

package/src/types/actions.ts

@@ -1,5 +1,6 @@
-import type { UniswapSwapProviderConfig } from '@/swap/providers/uniswap/types.js'
-import type { VelodromeSwapProviderConfig } from '@/swap/providers/velodrome/types.js'
+import type { UniswapSwapProviderConfig } from '@/actions/swap/providers/uniswap/types.js'
+import type { VelodromeSwapProviderConfig } from '@/actions/swap/providers/velodrome/types.js'
+import type { ChainManager } from '@/services/ChainManager.js'
 import type { Asset } from '@/types/asset.js'
 import type { ChainConfig } from '@/types/chain.js'
 import type { LendProviderConfig } from '@/types/lend/index.js'
@@ -18,11 +19,28 @@ type RequireAtLeastOne<T> = {
 }[keyof T]
 
 /**
- * Lending configuration — at least one provider must be configured
+ * Shared lend settings applied across all providers.
+ * Provider-level values override these when set.
+ */
+export interface LendSettings {
+  /**
+   * Default approval-amount strategy for ERC-20 → market approvals on supply.
+   * Per-call params override this; provider-level config overrides it for a
+   * single provider.
+   */
+  approvalMode?: ApprovalMode
+}
+
+/**
+ * Lending configuration — at least one provider must be configured.
+ * Shared settings go in `settings`; per-provider settings go under the provider key.
  */
 export type LendConfig = RequireAtLeastOne<{
   [K in keyof LendProviders]: LendProviderConfig
-}>
+}> & {
+  /** Shared settings applied across all lend providers */
+  settings?: LendSettings
+}
 
 /** Names of available swap providers — derived from SwapProviders registry */
 export type SwapProviderName = keyof SwapProviders
@@ -54,6 +72,12 @@ export interface SwapSettings {
   routing?: SwapRoutingStrategy
   /** Provider to prefer when routing produces a tie, or to always use when no routing strategy is set. */
   defaultProvider?: SwapProviderName
+  /**
+   * Default approval-amount strategy for swap approvals (Permit2 outer +
+   * inner). Per-call params override this; provider-level config overrides it
+   * for a single provider.
+   */
+  approvalMode?: ApprovalMode
 }
 
 /**
@@ -91,6 +115,44 @@ export interface AssetsConfig {
   block?: Asset[]
 }
 
+/**
+ * Shared dependencies derived from `ActionsConfig` at SDK construction time.
+ * @description Immutable bundle of resolved providers and services that the
+ * Actions SDK threads through its internal namespaces. Consumers that need
+ * provider references should receive an `ActionsContext` rather than a raw
+ * `ActionsConfig` — the providers in the context are already constructed and
+ * hold their own per-provider configuration (market allowlists, slippage
+ * defaults, etc.).
+ */
+export interface ActionsContext {
+  /** Chain manager wrapping the configured chains */
+  chainManager: ChainManager
+  /** Configured lend provider instances (each holds its own config) */
+  lendProviders: LendProviders
+  /** Configured swap provider instances (each holds its own config) */
+  swapProviders: SwapProviders
+  /** Resolved supported asset list (allowlist minus blocklist) */
+  supportedAssets: Asset[]
+  /** Shared swap settings applied across swap providers */
+  swapSettings?: SwapSettings
+}
+
+/**
+ * Approval amount strategy used when the SDK needs to grant a contract
+ * permission to spend the user's tokens (Permit2, Aave Pool, Morpho vault, ...).
+ *
+ * `"exact"` approves exactly the amount required for the current operation.
+ * Each subsequent operation needs its own approval transaction.
+ *
+ * `"max"` approves `maxUint256` for ERC-20 spenders / `maxUint160` for
+ * Permit2's inner allowance. Subsequent operations skip the re-approval
+ * round trip until the underlying allowance is consumed or expires.
+ *
+ * Default is `"exact"` for safety. Demo / dogfood configs typically opt into
+ * `"max"` to avoid an extra approval tx per swap or supply.
+ */
+export type ApprovalMode = 'exact' | 'max'
+
 /**
  * Actions SDK configuration
  * @description Configuration object for initializing the Actions SDK
@@ -113,14 +175,17 @@ export interface ActionsConfig<
 
 /**
  * Wallet configuration
- * @description Configuration for wallet providers
+ * @description Configuration for wallet providers. `hostedWalletConfig` is
+ * optional; when omitted, `wallet.toActionsWallet` accepts only a viem
+ * `LocalAccount` and `wallet.createSigner` / `wallet.hostedWalletProvider`
+ * are not available.
  */
 export type WalletConfig<
   THostedProviderType extends string,
   TConfigMap extends { [K in THostedProviderType]: unknown },
 > = {
-  /** Hosted wallet configuration */
-  hostedWalletConfig: HostedWalletConfig<THostedProviderType, TConfigMap>
+  /** Hosted wallet configuration (optional) */
+  hostedWalletConfig?: HostedWalletConfig<THostedProviderType, TConfigMap>
   /** Smart wallet configuration for ERC-4337 infrastructure */
   smartWalletConfig: SmartWalletConfig
 }

package/src/types/asset.ts

@@ -35,3 +35,11 @@ export interface TokenBalance {
     >
   >
 }
+
+/**
+ * Options accepted by the SDK's balance fetch surface (`Wallet.getBalance` and the underlying `fetchETHBalance` / `fetchERC20Balance` helpers).
+ * @property chainIds - Subset of supported chain ids to query. When omitted, all supported chains are queried. `Wallet.getBalance` validates this list via `validateChainIds`; the service helpers themselves trust their input.
+ */
+export interface BalanceFetchOptions {
+  chainIds?: readonly SupportedChainId[]
+}

package/src/types/common/FilterAssetChain.ts

@@ -0,0 +1,13 @@
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { Asset } from '@/types/asset.js'
+
+/**
+ * Common filter parameters shared across SDK list queries (Lend, Swap, Borrow, …).
+ * @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
+}

package/src/types/common/TransactionOptions.ts

@@ -0,0 +1,12 @@
+/**
+ * Transaction-level options shared across SDK domains (Lend, Swap, Borrow, …).
+ * @description Optional per-call overrides for transaction execution.
+ */
+export interface TransactionOptions {
+  /** Deadline for transaction (timestamp) */
+  deadline?: number
+  /** Gas limit override */
+  gasLimit?: bigint
+  /** Gas price override */
+  gasPrice?: bigint
+}

package/src/types/common/index.ts

@@ -0,0 +1,2 @@
+export * from '@/types/common/FilterAssetChain.js'
+export * from '@/types/common/TransactionOptions.js'

package/src/types/index.ts

@@ -1,6 +1,7 @@
 export * from '@/types/actions.js'
 export * from '@/types/asset.js'
 export * from '@/types/chain.js'
+export * from '@/types/common/index.js'
 export * from '@/types/lend/index.js'
 export * from '@/types/swap/index.js'
 export * from '@/types/transaction.js'

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,5 +1,5 @@
-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'
 

package/src/types/swap/base.ts

@@ -1,7 +1,8 @@
 import type { Address, Hex } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.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 {
@@ -9,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'
 
 /**
@@ -29,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
 }
 
 /**
@@ -88,10 +91,15 @@ export interface WalletSwapParams {
   slippage?: number
   /** Transaction deadline as Unix timestamp. Defaults to now + 1 minute. */
   deadline?: number
-  /** Recipient address. Defaults to wallet address. */
-  recipient?: Address
+  /** Recipient address or ENS name (e.g. "vitalik.eth"). Defaults to wallet address. */
+  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
 }
 
 /**
@@ -116,6 +124,8 @@ export interface ResolvedSwapParams {
   recipient: Address
   walletAddress: Address
   chainId: SupportedChainId
+  /** Resolved approval-amount strategy (per-call → wallet config → "exact"). */
+  approvalMode: ApprovalMode
 }
 
 /**
@@ -156,8 +166,8 @@ export interface SwapQuoteParams {
   slippage?: number
   /** Transaction deadline as Unix timestamp */
   deadline?: number
-  /** Recipient address */
-  recipient?: Address
+  /** Recipient address or ENS name (e.g. "vitalik.eth"). Defaults to wallet address. */
+  recipient?: Address | EnsName
   /** Explicitly select a swap provider */
   provider?: SwapProviderName
 }
@@ -238,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
 }
 
 /**