@eth-optimism/actions-sdk 0.5.0 → 0.6.0

package/src/wallet/core/namespace/WalletNamespace.ts

@@ -1,5 +1,9 @@
 import type { LocalAccount } from 'viem'
 
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { ActionsContext, SwapSettings } from '@/types/actions.js'
+import type { Asset } from '@/types/asset.js'
+import type { LendProviders, SwapProviders } from '@/types/providers.js'
 import type {
   CreateSmartWalletOptions,
   GetSmartWalletOptions,
@@ -10,6 +14,21 @@ import type { SmartWalletCreationResult } from '@/wallet/core/providers/smart/ab
 import type { WalletProvider } from '@/wallet/core/providers/WalletProvider.js'
 import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
 import type { SmartWallet } from '@/wallet/core/wallets/smart/abstract/SmartWallet.js'
+import { LocalWallet } from '@/wallet/node/wallets/local/LocalWallet.js'
+
+function isLocalAccount(value: unknown): value is LocalAccount {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+  const record = value as Record<string, unknown>
+  return (
+    record.type === 'local' &&
+    typeof record.address === 'string' &&
+    typeof record.signMessage === 'function' &&
+    typeof record.signTransaction === 'function' &&
+    (!('signTypedData' in record) || typeof record.signTypedData === 'function')
+  )
+}
 
 /**
  * Provider factory function for lazy initialization
@@ -21,6 +40,20 @@ type WalletProviderFactory<
   S extends SmartWalletProvider,
 > = () => Promise<WalletProvider<THostedProviderType, TToActionsMap, H, S>>
 
+/**
+ * Adaptive `toActionsWallet` parameter type
+ * @description Evaluates to the hosted provider's options map entry plus
+ * `LocalAccount` when a hosted provider is configured, or to `LocalAccount`
+ * only when no hosted provider is configured (`THostedProviderType` is
+ * `never`).
+ */
+type ToActionsWalletParam<
+  THostedProviderType extends string,
+  TToActionsMap extends Record<THostedProviderType, unknown>,
+> = [THostedProviderType] extends [never]
+  ? LocalAccount
+  : TToActionsMap[THostedProviderType] | LocalAccount
+
 /**
  * Wallet namespace that provides unified wallet operations
  * @description Provides access to wallet functionality through a single provider interface.
@@ -49,11 +82,17 @@ export class WalletNamespace<
   private _initPromise: Promise<
     WalletProvider<THostedProviderType, TToActionsMap, H, S>
   > | null = null
+  private readonly chainManager: ChainManager
+  private readonly lendProviders: LendProviders
+  private readonly swapProviders: SwapProviders
+  private readonly supportedAssets: Asset[]
+  private readonly swapSettings?: SwapSettings
 
   constructor(
     providerOrFactory:
       | WalletProvider<THostedProviderType, TToActionsMap, H, S>
       | WalletProviderFactory<THostedProviderType, TToActionsMap, H, S>,
+    context: ActionsContext,
   ) {
     if (typeof providerOrFactory === 'function') {
       this._providerFactory = providerOrFactory
@@ -61,19 +100,11 @@ export class WalletNamespace<
       this._provider = providerOrFactory
       this._providerFactory = () => Promise.resolve(providerOrFactory)
     }
-  }
-
-  private resolveProvider(): Promise<
-    WalletProvider<THostedProviderType, TToActionsMap, H, S>
-  > {
-    if (this._provider) return Promise.resolve(this._provider)
-    if (!this._initPromise) {
-      this._initPromise = this._providerFactory().then((provider) => {
-        this._provider = provider
-        return provider
-      })
-    }
-    return this._initPromise
+    this.chainManager = context.chainManager
+    this.lendProviders = context.lendProviders
+    this.swapProviders = context.swapProviders
+    this.supportedAssets = context.supportedAssets
+    this.swapSettings = context.swapSettings
   }
 
   /**
@@ -82,9 +113,15 @@ export class WalletNamespace<
    * advanced functionality beyond the unified interface is needed.
    * Lazily initializes the provider if not yet created.
    * @returns Promise resolving to the configured hosted wallet provider instance
+   * @throws Error if no hosted wallet provider is configured
    */
   async hostedWalletProvider(): Promise<H> {
     const provider = await this.resolveProvider()
+    if (!provider.hostedWalletProvider) {
+      throw new Error(
+        'Hosted wallet provider not configured. Please add hostedWalletConfig to ActionsConfig.wallet.',
+      )
+    }
     return provider.hostedWalletProvider
   }
 
@@ -141,18 +178,30 @@ export class WalletNamespace<
   }
 
   /**
-   * Convert a hosted wallet to an Actions wallet
-   * @description Converts a hosted wallet to an Actions wallet instance.
-   * @param params - Parameters for converting a hosted wallet to an Actions wallet
-   * @param params.walletId - Unique identifier for the hosted wallet
-   * @param params.address - Ethereum address of the hosted wallet
+   * Convert a hosted wallet or local account to an Actions wallet
+   * @description Accepts either provider-specific params (for Privy/Turnkey) or a viem
+   * `LocalAccount` directly, depending on configuration. When a hosted wallet provider
+   * is configured, both shapes are accepted; when none is configured, only a
+   * `LocalAccount` is accepted and provider params are a type error.
+   * @param params - Provider params or a viem LocalAccount
    * @returns Promise resolving to the Actions wallet instance
    */
   async toActionsWallet(
-    params: TToActionsMap[THostedProviderType],
+    params: ToActionsWalletParam<THostedProviderType, TToActionsMap>,
   ): Promise<Wallet> {
+    if (isLocalAccount(params)) {
+      return LocalWallet.create({
+        account: params,
+        chainManager: this.chainManager,
+        lendProviders: this.lendProviders,
+        swapProviders: this.swapProviders,
+        supportedAssets: this.supportedAssets,
+      })
+    }
     const provider = await this.resolveProvider()
-    return provider.hostedWalletToActionsWallet(params)
+    return provider.hostedWalletToActionsWallet(
+      params as TToActionsMap[THostedProviderType],
+    )
   }
 
   /**
@@ -174,4 +223,17 @@ export class WalletNamespace<
     const provider = await this.resolveProvider()
     return provider.getSmartWallet(params)
   }
+
+  private resolveProvider(): Promise<
+    WalletProvider<THostedProviderType, TToActionsMap, H, S>
+  > {
+    if (this._provider) return Promise.resolve(this._provider)
+    if (!this._initPromise) {
+      this._initPromise = this._providerFactory().then((provider) => {
+        this._provider = provider
+        return provider
+      })
+    }
+    return this._initPromise
+  }
 }

package/src/wallet/core/namespace/__tests__/WalletNamespace.spec.ts

@@ -1,5 +1,6 @@
 import type { PrivyClient } from '@privy-io/node'
 import { getAddress } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
 import { unichain } from 'viem/chains'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -9,8 +10,8 @@ import {
   getMockAuthorizationContext,
 } from '@/__mocks__/MockPrivyClient.js'
 import { getRandomAddress } from '@/__mocks__/utils.js'
+import { createMockLendProvider } from '@/actions/lend/__mocks__/MockLendProvider.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { createMockLendProvider } from '@/lend/__mocks__/MockLendProvider.js'
 import { MockChainManager } from '@/services/__mocks__/MockChainManager.js'
 import type { ChainManager } from '@/services/ChainManager.js'
 import { WalletNamespace } from '@/wallet/core/namespace/WalletNamespace.js'
@@ -52,7 +53,12 @@ describe('WalletNamespace', () => {
         hostedWalletProvider,
         smartWalletProvider,
       )
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       expect(await walletNamespace.hostedWalletProvider()).toBe(
         hostedWalletProvider,
@@ -79,7 +85,12 @@ describe('WalletNamespace', () => {
         hostedWalletProvider,
         smartWalletProvider,
       )
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       expect(await walletNamespace.smartWalletProvider()).toBe(
         smartWalletProvider,
@@ -103,12 +114,17 @@ describe('WalletNamespace', () => {
         smartWalletProvider,
       )
       const createSmartWalletSpy = vi.spyOn(walletProvider, 'createSmartWallet')
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       // Create a hosted wallet to use as signer
       const privyWallet = createMockPrivyWallet()
       const hostedWallet =
-        await walletProvider.hostedWalletProvider.toActionsWallet({
+        await walletProvider.hostedWalletProvider!.toActionsWallet({
           walletId: privyWallet.id,
           address: getAddress(privyWallet.address),
         })
@@ -143,12 +159,17 @@ describe('WalletNamespace', () => {
         hostedWalletProvider,
         smartWalletProvider,
       )
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       // Create a hosted wallet to use as signer
       const privyWallet = createMockPrivyWallet()
       const hostedWallet =
-        await walletProvider.hostedWalletProvider.toActionsWallet({
+        await walletProvider.hostedWalletProvider!.toActionsWallet({
           walletId: privyWallet.id,
           address: getAddress(privyWallet.address),
         })
@@ -228,11 +249,16 @@ describe('WalletNamespace', () => {
         smartWalletProvider,
       )
       const getSmartWalletSpy = vi.spyOn(walletProvider, 'getSmartWallet')
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       const privyWallet = createMockPrivyWallet()
       const hostedWallet =
-        await walletProvider.hostedWalletProvider.toActionsWallet({
+        await walletProvider.hostedWalletProvider!.toActionsWallet({
           walletId: privyWallet.id,
           address: getAddress(privyWallet.address),
         })
@@ -269,11 +295,16 @@ describe('WalletNamespace', () => {
         hostedWalletProvider,
         smartWalletProvider,
       )
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       const privyWallet = createMockPrivyWallet()
       const hostedWallet =
-        await walletProvider.hostedWalletProvider.toActionsWallet({
+        await walletProvider.hostedWalletProvider!.toActionsWallet({
           walletId: privyWallet.id,
           address: getAddress(privyWallet.address),
         })
@@ -305,16 +336,21 @@ describe('WalletNamespace', () => {
         hostedWalletProvider,
         smartWalletProvider,
       )
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       const privyWallet = createMockPrivyWallet()
       const hostedWallet =
-        await walletProvider.hostedWalletProvider.toActionsWallet({
+        await walletProvider.hostedWalletProvider!.toActionsWallet({
           walletId: privyWallet.id,
           address: getAddress(privyWallet.address),
         })
       const toActionsWalletSpy = vi.spyOn(
-        walletProvider.hostedWalletProvider,
+        walletProvider.hostedWalletProvider!,
         'toActionsWallet',
       )
 
@@ -333,6 +369,85 @@ describe('WalletNamespace', () => {
     })
   })
 
+  describe('toActionsWallet with LocalAccount', () => {
+    it('should create a LocalWallet from a viem LocalAccount', async () => {
+      const hostedWalletProvider = new PrivyHostedWalletProvider({
+        privyClient: mockPrivyClient,
+        authorizationContext: getMockAuthorizationContext(),
+        chainManager: mockChainManager,
+      })
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        { morpho: mockLendProvider },
+      )
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
+
+      const account = privateKeyToAccount(
+        '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+      )
+
+      const wallet = await walletNamespace.toActionsWallet(account)
+
+      expect(wallet.address).toBe(account.address)
+      expect(wallet.signer).toBe(account)
+    })
+
+    it('should expose lend namespace when an Aave provider is configured', async () => {
+      const mockAaveProvider = createMockLendProvider()
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        { aave: mockAaveProvider },
+      )
+      const walletProvider = new WalletProvider(undefined, smartWalletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: { aave: mockAaveProvider },
+        swapProviders: {},
+        supportedAssets: [],
+      })
+
+      const account = privateKeyToAccount(
+        '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+      )
+
+      const wallet = await walletNamespace.toActionsWallet(account)
+
+      expect(wallet.lend).toBeDefined()
+    })
+
+    it('should accept a LocalAccount when no hosted wallet provider is configured', async () => {
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        { morpho: mockLendProvider },
+      )
+      const walletProvider = new WalletProvider(undefined, smartWalletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
+
+      const account = privateKeyToAccount(
+        '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+      )
+
+      const wallet = await walletNamespace.toActionsWallet(account)
+
+      expect(wallet.address).toBe(account.address)
+      expect(wallet.signer).toBe(account)
+    })
+  })
+
   describe('createSigner', () => {
     it('should delegate to hosted wallet provider createSigner', async () => {
       const hostedWalletProvider = new PrivyHostedWalletProvider({
@@ -349,7 +464,12 @@ describe('WalletNamespace', () => {
         smartWalletProvider,
       )
       const createSignerSpy = vi.spyOn(walletProvider, 'createSigner')
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       const privyWallet = createMockPrivyWallet()
       const params = {
@@ -378,7 +498,12 @@ describe('WalletNamespace', () => {
         hostedWalletProvider,
         smartWalletProvider,
       )
-      const walletNamespace = new WalletNamespace(walletProvider)
+      const walletNamespace = new WalletNamespace(walletProvider, {
+        chainManager: mockChainManager,
+        lendProviders: {},
+        swapProviders: {},
+        supportedAssets: [],
+      })
 
       const privyWallet = createMockPrivyWallet()
       const signer = await walletNamespace.createSigner({

package/src/wallet/core/providers/WalletProvider.ts

@@ -22,10 +22,19 @@ export class WalletProvider<
   S extends SmartWalletProvider = SmartWalletProvider,
 > {
   constructor(
-    public readonly hostedWalletProvider: H,
+    public readonly hostedWalletProvider: H | undefined,
     public readonly smartWalletProvider: S,
   ) {}
 
+  private requireHostedWalletProvider(): H {
+    if (!this.hostedWalletProvider) {
+      throw new Error(
+        'Hosted wallet provider not configured. Please add hostedWalletConfig to ActionsConfig.wallet.',
+      )
+    }
+    return this.hostedWalletProvider
+  }
+
   /**
    * Create a new smart wallet
    * @description Creates a smart wallet and attempts to deploy it across all supported chains.
@@ -52,7 +61,7 @@ export class WalletProvider<
   async hostedWalletToActionsWallet(
     params: TToActionsMap[THostedProviderType],
   ): Promise<Wallet> {
-    return this.hostedWalletProvider.toActionsWallet(params)
+    return this.requireHostedWalletProvider().toActionsWallet(params)
   }
 
   /**
@@ -67,7 +76,7 @@ export class WalletProvider<
   async createSigner(
     params: TToActionsMap[THostedProviderType],
   ): Promise<LocalAccount> {
-    return this.hostedWalletProvider.createSigner(params)
+    return this.requireHostedWalletProvider().createSigner(params)
   }
 
   /**

package/src/wallet/core/providers/__tests__/WalletProvider.spec.ts

@@ -8,8 +8,8 @@ import {
   getMockAuthorizationContext,
 } from '@/__mocks__/MockPrivyClient.js'
 import { getRandomAddress } from '@/__mocks__/utils.js'
+import { createMockLendProvider } from '@/actions/lend/__mocks__/MockLendProvider.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { createMockLendProvider } from '@/lend/__mocks__/MockLendProvider.js'
 import { MockChainManager } from '@/services/__mocks__/MockChainManager.js'
 import type { ChainManager } from '@/services/ChainManager.js'
 import { DefaultSmartWalletProvider } from '@/wallet/core/providers/smart/default/DefaultSmartWalletProvider.js'

package/src/wallet/core/providers/hosted/registry/HostedWalletProviderRegistry.ts

@@ -1,3 +1,4 @@
+import { ProviderNotConfiguredError } from '@/core/error/errors.js'
 import type { HostedProviderFactory } from '@/wallet/core/providers/hosted/types/index.js'
 
 /**
@@ -29,7 +30,7 @@ export abstract class HostedWalletProviderRegistry<
     const factory = this.registry.get(type) as
       | HostedProviderFactory<TType, TInstanceMap[TType], TConfigMap[TType]>
       | undefined
-    if (!factory) throw new Error(`Unknown hosted wallet provider: ${type}`)
+    if (!factory) throw new ProviderNotConfiguredError({ provider: type })
     return factory
   }
 

package/src/wallet/core/providers/hosted/registry/__tests__/HostedWalletProviderRegistry.spec.ts

@@ -84,7 +84,7 @@ describe('HostedWalletProviderRegistry', () => {
     const registry = new TestHostedWalletProviderRegistry()
     // @ts-expect-error: testing runtime error for unknown type
     expect(() => registry.getFactory('unknown')).toThrow(
-      'Unknown hosted wallet provider: unknown',
+      "A 'unknown' provider is not configured",
     )
   })
 })

package/src/wallet/core/providers/smart/default/__tests__/DefaultSmartWalletProvider.spec.ts

@@ -15,8 +15,8 @@ import type {
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { getRandomAddress } from '@/__mocks__/utils.js'
+import { createMockLendProvider } from '@/actions/lend/__mocks__/MockLendProvider.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { createMockLendProvider } from '@/lend/__mocks__/MockLendProvider.js'
 import { MockChainManager } from '@/services/__mocks__/MockChainManager.js'
 import type { ChainManager } from '@/services/ChainManager.js'
 import { DefaultSmartWalletProvider } from '@/wallet/core/providers/smart/default/DefaultSmartWalletProvider.js'

package/src/wallet/core/utils/__tests__/executeTransactionBatch.spec.ts

@@ -0,0 +1,42 @@
+import type { Address } from 'viem'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { TransactionData } from '@/types/transaction.js'
+import { executeTransactionBatch } from '@/wallet/core/utils/executeTransactionBatch.js'
+import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+
+const CHAIN_ID = 10 as const
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000' as Address
+const TX_A: TransactionData = { to: ZERO_ADDRESS, data: '0xaa', value: 0n }
+const TX_B: TransactionData = { to: ZERO_ADDRESS, data: '0xbb', value: 0n }
+
+describe('executeTransactionBatch', () => {
+  let wallet: Wallet
+
+  beforeEach(() => {
+    wallet = {
+      send: vi.fn().mockResolvedValue({ kind: 'single' }),
+      sendBatch: vi.fn().mockResolvedValue({ kind: 'batch' }),
+    } as unknown as Wallet
+  })
+
+  it('throws when the transaction list is empty', async () => {
+    await expect(executeTransactionBatch(wallet, [], CHAIN_ID)).rejects.toThrow(
+      /empty/,
+    )
+  })
+
+  it('calls wallet.send for a single transaction', async () => {
+    const result = await executeTransactionBatch(wallet, [TX_A], CHAIN_ID)
+    expect(wallet.send).toHaveBeenCalledWith(TX_A, CHAIN_ID)
+    expect(wallet.sendBatch).not.toHaveBeenCalled()
+    expect(result).toEqual({ kind: 'single' })
+  })
+
+  it('calls wallet.sendBatch for multiple transactions', async () => {
+    const result = await executeTransactionBatch(wallet, [TX_A, TX_B], CHAIN_ID)
+    expect(wallet.sendBatch).toHaveBeenCalledWith([TX_A, TX_B], CHAIN_ID)
+    expect(wallet.send).not.toHaveBeenCalled()
+    expect(result).toEqual({ kind: 'batch' })
+  })
+})

package/src/{core → wallet/core}/utils/__tests__/retryOnStaleRead.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { retryOnStaleRead } from '@/core/utils/retryOnStaleRead.js'
+import { retryOnStaleRead } from '@/wallet/core/utils/retryOnStaleRead.js'
 
 describe('retryOnStaleRead', () => {
   it('returns immediately when value is fresh', async () => {

package/src/wallet/core/utils/executeTransactionBatch.ts

@@ -0,0 +1,37 @@
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { TransactionData } from '@/types/transaction.js'
+import type {
+  BatchTransactionReturnType,
+  TransactionReturnType,
+} from '@/wallet/core/wallets/abstract/types/index.js'
+import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+
+/**
+ * Dispatch a list of transactions to a wallet.
+ * @description Single-element → `wallet.send()`; multi-element →
+ * `wallet.sendBatch()`. An empty list is a programming error and throws.
+ *
+ * Shared by every wallet-signing namespace (WalletLendNamespace,
+ * WalletSwapNamespace, WalletBorrowNamespace, …). Implemented as a
+ * module-level helper rather than a base class so namespaces can inherit
+ * from their domain-specific base (BaseLendNamespace etc.) without a
+ * multi-inheritance bind.
+ * @param wallet - The wallet that signs and sends the transactions
+ * @param transactions - Non-empty list of transactions to dispatch
+ * @param chainId - Target chain for the transactions
+ * @returns Receipt(s) from the underlying send / sendBatch call
+ * @throws Error if `transactions` is empty
+ */
+export async function executeTransactionBatch(
+  wallet: Wallet,
+  transactions: readonly TransactionData[],
+  chainId: SupportedChainId,
+): Promise<TransactionReturnType | BatchTransactionReturnType> {
+  if (transactions.length === 0) {
+    throw new Error('executeTransactionBatch: empty transaction list')
+  }
+  if (transactions.length === 1) {
+    return wallet.send(transactions[0], chainId)
+  }
+  return wallet.sendBatch(transactions, chainId)
+}

package/src/wallet/core/wallets/abstract/Wallet.ts

@@ -1,15 +1,16 @@
 import type { Address, LocalAccount } from 'viem'
 
+import { WalletLendNamespace } from '@/actions/lend/namespaces/WalletLendNamespace.js'
+import { WalletSwapNamespace } from '@/actions/swap/namespaces/WalletSwapNamespace.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { EnsNamespace } from '@/ens/index.js'
-import { WalletLendNamespace } from '@/lend/namespaces/WalletLendNamespace.js'
 import type { ChainManager } from '@/services/ChainManager.js'
+import { EnsNamespace } from '@/services/nameservices/ens/index.js'
 import { fetchERC20Balance, fetchETHBalance } from '@/services/tokenBalance.js'
-import { WalletSwapNamespace } from '@/swap/namespaces/WalletSwapNamespace.js'
 import type { SwapSettings } from '@/types/actions.js'
-import type { Asset, TokenBalance } from '@/types/asset.js'
+import type { Asset, BalanceFetchOptions, TokenBalance } from '@/types/asset.js'
 import type { LendProviders, SwapProviders } from '@/types/providers.js'
 import type { TransactionData } from '@/types/transaction.js'
+import { validateBalanceFetchOptions } from '@/utils/validation.js'
 import type {
   BatchTransactionReturnType,
   TransactionReturnType,
@@ -84,18 +85,19 @@ export abstract class Wallet {
   }
 
   /**
-   * Get asset balances across all supported chains
-   * @description Fetches ETH and ERC20 token balances for this wallet across all supported networks.
-   * Uses the configured supported assets from ActionsConfig.assets if provided.
+   * Get asset balances across the requested chains (or all supported chains).
+   * @description Fetches ETH and ERC20 token balances for this wallet. By default queries every chain returned by the SDK's `ChainManager`. Pass `options.chainIds` to restrict the query to a subset of those chains; each id is validated against the configured chains and an `InvalidParamsError` / `ChainNotSupportedError` is thrown for unusable input. Uses the configured supported assets from `ActionsConfig.assets` if provided.
+   * @param options - Optional `chainIds` filter
    * @returns Promise resolving to array of token balances with chain breakdown
    */
-  async getBalance(): Promise<TokenBalance[]> {
-    const tokenBalancePromises = this.supportedAssets.map(async (asset) => {
-      return fetchERC20Balance(this.chainManager, this.address, asset)
-    })
-    const ethBalancePromise = fetchETHBalance(this.chainManager, this.address)
-
-    return Promise.all([ethBalancePromise, ...tokenBalancePromises])
+  async getBalance(options?: BalanceFetchOptions): Promise<TokenBalance[]> {
+    validateBalanceFetchOptions(options, this.chainManager)
+    return Promise.all([
+      fetchETHBalance(this.chainManager, this.address, options),
+      ...this.supportedAssets.map((asset) =>
+        fetchERC20Balance(this.chainManager, this.address, asset, options),
+      ),
+    ])
   }
 
   /**
@@ -163,7 +165,7 @@ export abstract class Wallet {
    * @returns Promise resolving to the transaction hash
    */
   abstract sendBatch(
-    transactionData: TransactionData[],
+    transactionData: readonly TransactionData[],
     chainId: SupportedChainId,
   ): Promise<BatchTransactionReturnType>
 }