@eth-optimism/actions-sdk 0.5.0 → 0.6.0

package/src/services/{ChainManager.spec.ts → __tests__/ChainManager.spec.ts}

@@ -90,7 +90,7 @@ describe('ChainManager', () => {
       ]
 
       expect(() => new ChainManager(invalidChainConfigs)).toThrow(
-        'Chain not found for ID: 99999',
+        'Chain 99999 is not supported',
       )
     })
 
@@ -100,7 +100,7 @@ describe('ChainManager', () => {
         { chainId: unichain.id, rpcUrls: ['https://another.rpc'] },
       ]
       expect(() => new ChainManager(multiChainConfigs)).toThrow(
-        `Public client already configured for chain ID: ${unichain.id}`,
+        `Chain ${unichain.id} is not supported`,
       )
     })
   })
@@ -117,7 +117,7 @@ describe('ChainManager', () => {
       const unsupportedChainId = 999 as unknown as SupportedChainId
 
       expect(() => chainManager.getPublicClient(unsupportedChainId)).toThrow(
-        'No public client configured for chain ID: 999',
+        'Chain 999 is not supported',
       )
     })
   })
@@ -183,7 +183,7 @@ describe('ChainManager', () => {
 
       expect(() =>
         chainManager.getTransportForChain(unsupportedChainId),
-      ).toThrow('No chain config found for chain ID: 999')
+      ).toThrow('Chain 999 is not supported')
     })
   })
 
@@ -306,7 +306,7 @@ describe('ChainManager', () => {
       const mgr = new ChainManager(configs)
 
       expect(() => mgr.getBundlerClient(unichain.id, mockAccount)).toThrow(
-        `No bundler configured for chain ID: ${unichain.id}`,
+        `Chain ${unichain.id} is not supported`,
       )
     })
 
@@ -325,7 +325,7 @@ describe('ChainManager', () => {
       const mgr = new ChainManager(configs)
 
       expect(() => mgr.getBundlerClient(unichain.id, mockAccount)).toThrow(
-        `No bundler URL configured for chain ID: ${unichain.id}`,
+        `Chain ${unichain.id} is not supported`,
       )
     })
   })

package/src/services/{tokenBalance.spec.ts → __tests__/tokenBalance.spec.ts}

@@ -1,5 +1,5 @@
 import type { Address } from 'viem'
-import { unichain } from 'viem/chains'
+import { base, optimism, unichain } from 'viem/chains'
 import { beforeEach, describe, expect, it } from 'vitest'
 
 import { MockUSDCAsset } from '@/__mocks__/MockAssets.js'
@@ -20,6 +20,12 @@ describe('TokenBalance', () => {
     }) as any
   })
 
+  const multiChainManager = (): ChainManager =>
+    new MockChainManager({
+      supportedChains: [optimism.id, base.id, unichain.id],
+      defaultBalance: 1000000n,
+    }) as unknown as ChainManager
+
   describe('fetchBalance', () => {
     it('should fetch token balance across supported chains', async () => {
       const balance = await fetchERC20Balance(
@@ -85,5 +91,54 @@ describe('TokenBalance', () => {
         },
       })
     })
+
+    it('queries only the requested chains when chainIds is provided', async () => {
+      const cm = multiChainManager()
+
+      const balance = await fetchETHBalance(cm, walletAddress, {
+        chainIds: [base.id],
+      })
+
+      expect(balance.chains).toEqual({
+        [base.id]: { balance: 0.000000000001, balanceRaw: 1000000n },
+      })
+      expect(balance.totalBalanceRaw).toBe(1000000n)
+      expect(cm.getPublicClient).toHaveBeenCalledTimes(1)
+      expect(cm.getPublicClient).toHaveBeenCalledWith(base.id)
+    })
+  })
+
+  describe('fetchERC20Balance with chainIds filter', () => {
+    it('queries only the requested chains', async () => {
+      const cm = multiChainManager()
+
+      const balance = await fetchERC20Balance(
+        cm,
+        walletAddress,
+        MockUSDCAsset,
+        { chainIds: [optimism.id, base.id] },
+      )
+
+      expect(Object.keys(balance.chains).map(Number).sort()).toEqual(
+        [optimism.id, base.id].sort(),
+      )
+      expect(balance.totalBalanceRaw).toBe(2000000n)
+    })
+
+    it('silently skips requested chains where the asset has no address', async () => {
+      const cm = multiChainManager()
+      const opOnly: Asset = {
+        ...MockUSDCAsset,
+        address: { [optimism.id]: MockUSDCAsset.address[optimism.id] } as any,
+      }
+
+      const balance = await fetchERC20Balance(cm, walletAddress, opOnly, {
+        chainIds: [optimism.id, base.id],
+      })
+
+      expect(balance.chains).toEqual({
+        [optimism.id]: { balance: 1, balanceRaw: 1000000n },
+      })
+    })
   })
 })

package/src/{ens → services/nameservices/ens}/EnsNamespace.ts

@@ -3,7 +3,7 @@ import { mainnet } from 'viem/chains'
 import { normalize } from 'viem/ens'
 
 import type { ChainManager } from '@/services/ChainManager.js'
-import { resolveAddress } from '@/utils/ens.js'
+import { resolveAddress } from '@/services/nameservices/ens/utils.js'
 
 import { EnsResolutionError, EnsRpcError } from './errors.js'
 import {

package/src/{ens → services/nameservices/ens/__tests__}/EnsNamespace.spec.ts

@@ -2,10 +2,12 @@ import type { Address, PublicClient } from 'viem'
 import { describe, expect, it, vi } from 'vitest'
 
 import type { ChainManager } from '@/services/ChainManager.js'
-
-import { EnsNamespace } from './EnsNamespace.js'
-import { EnsResolutionError, EnsRpcError } from './errors.js'
-import type { EnsName } from './types.js'
+import { EnsNamespace } from '@/services/nameservices/ens/EnsNamespace.js'
+import {
+  EnsResolutionError,
+  EnsRpcError,
+} from '@/services/nameservices/ens/errors.js'
+import type { EnsName } from '@/services/nameservices/ens/types.js'
 
 const REAL_ADDRESS = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' as Address
 const ENS_NAME = 'vitalik.eth' as EnsName

package/src/{utils/ens.test.ts → services/nameservices/ens/__tests__/utils.spec.ts}

@@ -2,7 +2,7 @@ import type { Address, PublicClient } from 'viem'
 import { zeroAddress } from 'viem'
 import { describe, expect, it, vi } from 'vitest'
 
-import { resolveAddress } from '@/utils/ens.js'
+import { resolveAddress } from '@/services/nameservices/ens/utils.js'
 
 const REAL_ADDRESS = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' as Address
 const ZERO_ADDRESS = zeroAddress
@@ -43,7 +43,8 @@ describe('resolveAddress', () => {
     })
 
     it('throws EnsNotConfiguredError when no mainnet client is provided', async () => {
-      const { EnsNotConfiguredError } = await import('@/ens/errors.js')
+      const { EnsNotConfiguredError } =
+        await import('@/services/nameservices/ens/errors.js')
       await expect(resolveAddress('vitalik.eth')).rejects.toThrow(
         EnsNotConfiguredError,
       )

package/src/{ens → services/nameservices/ens}/index.ts

@@ -10,3 +10,8 @@ export {
   isEnsName,
   type NameServiceProvider,
 } from './types.js'
+export {
+  passthroughResolver,
+  type RecipientResolver,
+  resolveAddress,
+} from './utils.js'

package/src/{utils/ens.ts → services/nameservices/ens/utils.ts}

@@ -6,10 +6,10 @@ import {
   EnsNotConfiguredError,
   EnsResolutionError,
   EnsRpcError,
-} from '@/ens/errors.js'
-import type { EnsName } from '@/ens/types.js'
+} from '@/services/nameservices/ens/errors.js'
+import type { EnsName } from '@/services/nameservices/ens/types.js'
 
-export { type EnsName, isEnsName } from '@/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 = (

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'