@eth-optimism/actions-sdk 0.5.0 → 0.7.0

package/src/services/ChainManager.ts

@@ -11,10 +11,28 @@ import {
 } from 'viem'
 import type { BundlerClient, SmartAccount } from 'viem/account-abstraction'
 import { createBundlerClient } from 'viem/account-abstraction'
+import { mainnet, sepolia } from 'viem/chains'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { ChainNotSupportedError } from '@/core/error/errors.js'
 import type { ChainConfig } from '@/types/chain.js'
 
+/** viem `pollingInterval` (ms) for L2-class chains with ~1-2s blocks. */
+const L2_POLLING_INTERVAL_MS = 1000
+/** viem `pollingInterval` (ms) for L1-class chains with ~12s blocks. */
+const L1_POLLING_INTERVAL_MS = 4000
+
+const L1_CHAIN_IDS: ReadonlySet<SupportedChainId> = new Set([
+  mainnet.id,
+  sepolia.id,
+])
+
+function pollingIntervalForChain(chainId: SupportedChainId): number {
+  return L1_CHAIN_IDS.has(chainId)
+    ? L1_POLLING_INTERVAL_MS
+    : L2_POLLING_INTERVAL_MS
+}
+
 /**
  * Chain Manager Service
  * @description Manages public clients and chain infrastructure for the Verbs SDK.
@@ -44,7 +62,10 @@ export class ChainManager {
   getPublicClient(chainId: SupportedChainId): PublicClient {
     const client = this.publicClients.get(chainId)
     if (!client) {
-      throw new Error(`No public client configured for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     return client
   }
@@ -73,7 +94,10 @@ export class ChainManager {
     const chainConfig = this.getChainConfig(chainId)
     const bundlerConfig = chainConfig.bundler
     if (!bundlerConfig) {
-      throw new Error(`No bundler configured for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     if (bundlerConfig.type === 'pimlico') {
       return this.getPimlicoBundlerClient(
@@ -84,11 +108,15 @@ export class ChainManager {
     }
     const bundlerUrl = this.getBundlerUrl(chainId)
     if (!bundlerUrl) {
-      throw new Error(`No bundler URL configured for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     const client = createPublicClient({
       chain: this.getChain(chainId),
       transport: http(bundlerUrl),
+      pollingInterval: pollingIntervalForChain(chainId),
     })
     return createBundlerClient({
       account,
@@ -118,7 +146,10 @@ export class ChainManager {
   getBundlerUrl(chainId: SupportedChainId): string | undefined {
     const chainConfig = this.getChainConfig(chainId)
     if (!chainConfig.bundler) {
-      throw new Error(`No bundler configured for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     return chainConfig.bundler.url
   }
@@ -167,16 +198,18 @@ export class ChainManager {
     for (const chainConfig of chains) {
       const chain = chainById[chainConfig.chainId]
       if (!chain) {
-        throw new Error(`Chain not found for ID: ${chainConfig.chainId}`)
+        throw new ChainNotSupportedError({ chainId: chainConfig.chainId })
       }
       if (clients.has(chainConfig.chainId)) {
-        throw new Error(
-          `Public client already configured for chain ID: ${chainConfig.chainId}`,
-        )
+        throw new ChainNotSupportedError({
+          chainId: chainConfig.chainId,
+          supportedChainIds: Array.from(clients.keys()),
+        })
       }
       const client = createPublicClient({
         chain,
         transport: this.getTransportForChain(chainConfig.chainId),
+        pollingInterval: pollingIntervalForChain(chainConfig.chainId),
       })
 
       clients.set(chainConfig.chainId, client)
@@ -193,7 +226,10 @@ export class ChainManager {
   private getChainConfig(chainId: SupportedChainId): ChainConfig {
     const chainConfig = this.chainConfigs.find((c) => c.chainId === chainId)
     if (!chainConfig) {
-      throw new Error(`No chain config found for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     return chainConfig
   }

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,16 +1,27 @@
-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'
-import type { LendProviders, SwapProviders } from '@/types/providers.js'
+import type {
+  LendProviders,
+  SwapProviderName,
+  SwapProviders,
+} from '@/types/providers.js'
 import type { SwapProviderConfig } from '@/types/swap/index.js'
 import type { ProviderSpec } from '@/wallet/core/providers/hosted/types/index.js'
 
 // Re-export provider configs for convenience
 export type { LendProviderConfig, SwapProviderConfig }
-// Re-export centralized provider maps
-export type { LendProviders, SwapProviders } from '@/types/providers.js'
+// Re-export centralized provider maps and constants
+export type {
+  LendProviderName,
+  LendProviders,
+  SwapProviderName,
+  SwapProviders,
+} from '@/types/providers.js'
+export { LEND_PROVIDER_NAMES, SWAP_PROVIDER_NAMES } from '@/types/providers.js'
 
 /** Require at least one property to be defined */
 type RequireAtLeastOne<T> = {
@@ -18,17 +29,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
-}>
-
-/** Names of available swap providers — derived from SwapProviders registry */
-export type SwapProviderName = keyof SwapProviders
-
-/** Names of available lend providers — derived from LendProviders registry */
-export type LendProviderName = keyof LendProviders
+}> & {
+  /** Shared settings applied across all lend providers */
+  settings?: LendSettings
+}
 
 /** Routing strategy for selecting a provider when multiple are configured. */
 export type SwapRoutingStrategy = 'price'
@@ -54,6 +76,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 +119,55 @@ 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 const APPROVAL_MODES = ['exact', 'max'] as const
+
+export type ApprovalMode = (typeof APPROVAL_MODES)[number]
+
+/**
+ * The lend write actions exposed by the SDK's wallet namespace
+ * (`openPosition` / `closePosition`). Useful for callers that emit
+ * action-tagged output envelopes or branch on the action being performed.
+ */
+export const LEND_ACTIONS = ['open', 'close'] as const
+
+export type LendAction = (typeof LEND_ACTIONS)[number]
+
 /**
  * Actions SDK configuration
  * @description Configuration object for initializing the Actions SDK
@@ -113,14 +190,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'