@eth-optimism/actions-sdk 0.0.0-main-20251009211102

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

@@ -0,0 +1,374 @@
+import type { WaitForUserOperationReceiptReturnType } from 'viem/account-abstraction'
+import { unichain } from 'viem/chains'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import { MockChainManager } from '@/test/MockChainManager.js'
+import { createMockLendProvider } from '@/test/MockLendProvider.js'
+import { createMockPrivyClient } from '@/test/MockPrivyClient.js'
+import { getRandomAddress } from '@/test/utils.js'
+import { DefaultSmartWalletProvider } from '@/wallet/core/providers/smart/default/DefaultSmartWalletProvider.js'
+import { WalletProvider } from '@/wallet/core/providers/WalletProvider.js'
+import { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+import { DefaultSmartWallet } from '@/wallet/core/wallets/smart/default/DefaultSmartWallet.js'
+import { SmartWalletDeploymentError } from '@/wallet/core/wallets/smart/error/errors.js'
+import { PrivyHostedWalletProvider } from '@/wallet/node/providers/hosted/privy/PrivyHostedWalletProvider.js'
+import type { PrivyWallet } from '@/wallet/node/wallets/hosted/privy/PrivyWallet.js'
+
+const mockChainManager = new MockChainManager({
+  supportedChains: [unichain.id],
+}) as unknown as ChainManager
+const mockLendProvider = createMockLendProvider()
+
+describe('WalletProvider', () => {
+  let mockPrivyClient: ReturnType<typeof createMockPrivyClient>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockPrivyClient = createMockPrivyClient('test-app-id', 'test-app-secret')
+  })
+
+  describe('createSmartWallet', () => {
+    it('should create a smart wallet and return deployment result', async () => {
+      const hostedWalletProvider = new PrivyHostedWalletProvider(
+        mockPrivyClient,
+        mockChainManager,
+      )
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+
+      // Create a hosted wallet to use as signer
+      const hostedWallet = (await hostedWalletProvider.toActionsWallet({
+        walletId: 'mock-wallet-1',
+        address: getRandomAddress(),
+      })) as PrivyWallet
+      const signer = hostedWallet.signer
+      const signers = [getRandomAddress(), hostedWallet.address]
+      const nonce = BigInt(123)
+
+      const mockWallet = {} as DefaultSmartWallet
+      const mockDeploymentResult = {
+        wallet: mockWallet,
+        deployments: [
+          {
+            chainId: unichain.id as SupportedChainId,
+            receipt: undefined,
+            success: true,
+          },
+        ],
+      }
+
+      const createWalletSpy = vi
+        .spyOn(smartWalletProvider, 'createWallet')
+        .mockResolvedValue(mockDeploymentResult)
+
+      const result = await walletProvider.createSmartWallet({
+        signers,
+        signer,
+        nonce,
+      })
+
+      expect(createWalletSpy).toHaveBeenCalledWith({
+        signers,
+        signer,
+        nonce,
+      })
+      expect(result).toEqual(mockDeploymentResult)
+    })
+
+    it('should pass through deployment successes and failures', async () => {
+      const hostedWalletProvider = new PrivyHostedWalletProvider(
+        mockPrivyClient,
+        mockChainManager,
+      )
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+
+      const hostedWallet = (await hostedWalletProvider.toActionsWallet({
+        walletId: 'mock-wallet-1',
+        address: getRandomAddress(),
+      })) as PrivyWallet
+      const signer = hostedWallet.signer
+      const signers = [getRandomAddress(), hostedWallet.address]
+
+      const mockWallet = {} as DefaultSmartWallet
+      const mockReceipt = {
+        success: true,
+      } as unknown as WaitForUserOperationReceiptReturnType
+      const mockDeploymentResult = {
+        wallet: mockWallet,
+        deployments: [
+          {
+            chainId: unichain.id as SupportedChainId,
+            receipt: mockReceipt,
+            success: true,
+          },
+          {
+            chainId: 8453 as SupportedChainId,
+            receipt: mockReceipt,
+            success: false,
+            error: new SmartWalletDeploymentError('Deployment failed', 8453),
+          },
+        ],
+      }
+
+      vi.spyOn(smartWalletProvider, 'createWallet').mockResolvedValue(
+        mockDeploymentResult,
+      )
+
+      const result = await walletProvider.createSmartWallet({
+        signers,
+        signer,
+      })
+
+      expect(result).toEqual(mockDeploymentResult)
+    })
+
+    it('should forward deploymentChainIds parameter', async () => {
+      const hostedWalletProvider = new PrivyHostedWalletProvider(
+        mockPrivyClient,
+        mockChainManager,
+      )
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+
+      const hostedWallet = (await hostedWalletProvider.toActionsWallet({
+        walletId: 'mock-wallet-1',
+        address: getRandomAddress(),
+      })) as PrivyWallet
+      const signer = hostedWallet.signer
+      const signers = [getRandomAddress(), hostedWallet.address]
+      const deploymentChainIds: SupportedChainId[] = [8453]
+
+      const mockWallet = {} as DefaultSmartWallet
+      const mockDeploymentResult = {
+        wallet: mockWallet,
+        deployments: [
+          {
+            chainId: 8453 as SupportedChainId,
+            receipt: undefined,
+            success: true,
+          },
+        ],
+      }
+
+      const createWalletSpy = vi
+        .spyOn(smartWalletProvider, 'createWallet')
+        .mockResolvedValue(mockDeploymentResult)
+
+      const result = await walletProvider.createSmartWallet({
+        signers,
+        signer,
+        deploymentChainIds,
+      })
+
+      expect(createWalletSpy).toHaveBeenCalledWith({
+        signers,
+        signer,
+        deploymentChainIds,
+      })
+      expect(result).toEqual(mockDeploymentResult)
+    })
+
+    it('should throw error if signer is not in signers array', async () => {
+      const hostedWalletProvider = new PrivyHostedWalletProvider(
+        mockPrivyClient,
+        mockChainManager,
+      )
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+
+      const hostedWallet = (await hostedWalletProvider.toActionsWallet({
+        walletId: 'mock-wallet-1',
+        address: getRandomAddress(),
+      })) as PrivyWallet
+      const signer = hostedWallet.signer
+      // Signer is NOT in the signers array
+      const signers = [getRandomAddress(), getRandomAddress()]
+
+      await expect(
+        walletProvider.createSmartWallet({
+          signers,
+          signer,
+        }),
+      ).rejects.toThrow('Signer does not match any signer in the signers array')
+    })
+  })
+
+  describe('getSmartWallet', () => {
+    it('should get a smart wallet with provided signer', async () => {
+      const hostedWalletProvider = new PrivyHostedWalletProvider(
+        mockPrivyClient,
+        mockChainManager,
+      )
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const mockWalletAddress = getRandomAddress()
+      const getWalletAddressSpy = vi
+        .spyOn(smartWalletProvider, 'getWalletAddress')
+        .mockResolvedValue(mockWalletAddress)
+      const getWalletSpy = vi.spyOn(smartWalletProvider, 'getWallet')
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+
+      const hostedWallet = (await hostedWalletProvider.toActionsWallet({
+        walletId: 'mock-wallet-1',
+        address: getRandomAddress(),
+      })) as PrivyWallet
+      const signer = hostedWallet.signer
+      const deploymentSigners = [hostedWallet.address, getRandomAddress()]
+      const nonce = BigInt(789)
+
+      const smartWallet = await walletProvider.getSmartWallet({
+        signer,
+        deploymentSigners,
+        signers: [signer.address],
+        nonce,
+      })
+
+      expect(smartWallet).toBeInstanceOf(DefaultSmartWallet)
+      expect(getWalletAddressSpy).toHaveBeenCalledWith({
+        signers: deploymentSigners,
+        nonce,
+      })
+      expect(getWalletSpy).toHaveBeenCalledWith({
+        walletAddress: mockWalletAddress,
+        signer,
+        signers: [signer.address],
+      })
+    })
+
+    it('should throw error when getting smart wallet without required parameters', async () => {
+      const hostedWalletProvider = new PrivyHostedWalletProvider(
+        mockPrivyClient,
+        mockChainManager,
+      )
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+
+      const hostedWallet = (await hostedWalletProvider.toActionsWallet({
+        walletId: 'mock-wallet-1',
+        address: getRandomAddress(),
+      })) as PrivyWallet
+      const signer = hostedWallet.signer
+
+      await expect(
+        walletProvider.getSmartWallet({
+          signer,
+          signers: [signer.address],
+          // Missing both walletAddress and deploymentSigners
+        }),
+      ).rejects.toThrow(
+        'Either walletAddress or deploymentSigners array must be provided to locate the smart wallet',
+      )
+    })
+  })
+
+  describe('hostedWalletToActionsWallet', () => {
+    it('should convert a hosted wallet to an Actions wallet', async () => {
+      const hostedWalletProvider = new PrivyHostedWalletProvider(
+        mockPrivyClient,
+        mockChainManager,
+      )
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+      const toActionsWalletSpy = vi.spyOn(
+        hostedWalletProvider,
+        'toActionsWallet',
+      )
+
+      const privyWallet = await mockPrivyClient.walletApi.createWallet({
+        chainType: 'ethereum',
+      })
+      const hostedWallet = await walletProvider.hostedWalletToActionsWallet({
+        walletId: privyWallet.id,
+        address: privyWallet.address,
+      })
+
+      expect(toActionsWalletSpy).toHaveBeenCalledWith({
+        walletId: privyWallet.id,
+        address: privyWallet.address,
+      })
+      expect(hostedWallet).toBeInstanceOf(Wallet)
+      expect(hostedWallet.signer.address).toBe(privyWallet.address)
+      expect(hostedWallet.address).toBe(privyWallet.address)
+    })
+  })
+
+  describe('createSigner', () => {
+    it('should delegate to hosted wallet provider createSigner', async () => {
+      const mockPrivyClient = createMockPrivyClient(
+        'test-app-id',
+        'test-app-secret',
+      )
+      const hostedWalletProvider = new PrivyHostedWalletProvider(
+        mockPrivyClient,
+        mockChainManager,
+      )
+      const smartWalletProvider = new DefaultSmartWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const walletProvider = new WalletProvider(
+        hostedWalletProvider,
+        smartWalletProvider,
+      )
+      const createSignerSpy = vi.spyOn(hostedWalletProvider, 'createSigner')
+
+      const privyWallet = await mockPrivyClient.walletApi.createWallet({
+        chainType: 'ethereum',
+      })
+      const params = {
+        walletId: privyWallet.id,
+        address: privyWallet.address,
+      }
+
+      const signer = await walletProvider.createSigner(params)
+
+      expect(createSignerSpy).toHaveBeenCalledWith(params)
+      expect(signer.address).toBe(privyWallet.address)
+      expect(signer.type).toBe('local')
+    })
+  })
+})

package/src/wallet/core/providers/hosted/abstract/HostedWalletProvider.ts

@@ -0,0 +1,45 @@
+import type { LocalAccount } from 'viem'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { LendConfig, LendProvider } from '@/types/lend/index.js'
+import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+
+/**
+ * Base hosted wallet provider class
+ * @description Abstract base class for hosted wallet provider implementations (Privy, Dynamic, etc.).
+ * Provides a standard interface for creating and retrieving hosted wallets that can be used
+ * as signers for smart wallets or standalone wallet functionality.
+ */
+export abstract class HostedWalletProvider<
+  TType extends string,
+  TOptionsMap extends Record<TType, unknown>,
+> {
+  protected chainManager: ChainManager
+  protected lendProvider?: LendProvider<LendConfig>
+
+  protected constructor(
+    chainManager: ChainManager,
+    lendProvider?: LendProvider<LendConfig>,
+  ) {
+    this.chainManager = chainManager
+    this.lendProvider = lendProvider
+  }
+  /**
+   * 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
+   * @returns Promise resolving to the Actions wallet instance
+   */
+  abstract toActionsWallet(params: TOptionsMap[TType]): Promise<Wallet>
+
+  /**
+   * Create a viem LocalAccount signer from the hosted wallet
+   * @description Produces a signing account backed by the hosted wallet without wrapping
+   * it in a full Actions wallet. This is useful when you need to pass the signer
+   * into an Actions smart wallet as a signer, for lower-level viem operations, or
+   * for passing to other libraries that accept a viem `LocalAccount`.
+   * @param params - Configuration for the signer
+   * @returns Promise resolving to a viem `LocalAccount` with the hosted wallet as the signer backend
+   */
+  abstract createSigner(params: TOptionsMap[TType]): Promise<LocalAccount>
+}

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

@@ -0,0 +1,46 @@
+import type { HostedProviderFactory } from '@/wallet/core/providers/hosted/types/index.js'
+
+/**
+ * Base registry for hosted wallet providers.
+ * Maintains a map of provider factories keyed by provider type.
+ * Environment-specific subclasses register available providers.
+ */
+export abstract class HostedWalletProviderRegistry<
+  TInstanceMap extends Record<TProviderType, unknown>,
+  TConfigMap extends Record<TProviderType, unknown>,
+  TProviderType extends keyof TInstanceMap & keyof TConfigMap & string,
+> {
+  protected readonly registry = new Map<
+    TProviderType,
+    HostedProviderFactory<
+      TProviderType,
+      TInstanceMap[TProviderType],
+      TConfigMap[TProviderType]
+    >
+  >()
+
+  /**
+   * Get a provider factory by type.
+   * Throws if the provider type is not registered.
+   */
+  getFactory<TType extends TProviderType>(
+    type: TType,
+  ): HostedProviderFactory<TType, TInstanceMap[TType], TConfigMap[TType]> {
+    const factory = this.registry.get(type) as
+      | HostedProviderFactory<TType, TInstanceMap[TType], TConfigMap[TType]>
+      | undefined
+    if (!factory) throw new Error(`Unknown hosted wallet provider: ${type}`)
+    return factory
+  }
+
+  /**
+   * Register a provider factory if not already present.
+   * Intended for use by subclasses during construction.
+   */
+  protected register<T extends TProviderType>(
+    factory: HostedProviderFactory<T, TInstanceMap[T], TConfigMap[T]>,
+  ) {
+    if (!this.registry.has(factory.type))
+      this.registry.set(factory.type, factory)
+  }
+}

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

@@ -0,0 +1,77 @@
+import type { PrivyClient } from '@privy-io/server-auth'
+import { unichain } from 'viem/chains'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import { MockChainManager } from '@/test/MockChainManager.js'
+import { createMockPrivyClient } from '@/test/MockPrivyClient.js'
+import { HostedWalletProviderRegistry } from '@/wallet/core/providers/hosted/registry/HostedWalletProviderRegistry.js'
+import { PrivyHostedWalletProvider } from '@/wallet/node/providers/hosted/privy/PrivyHostedWalletProvider.js'
+import type { NodeOptionsMap } from '@/wallet/node/providers/hosted/types/index.js'
+
+type TestInstanceMap = { privy: PrivyHostedWalletProvider }
+class TestHostedWalletProviderRegistry extends HostedWalletProviderRegistry<
+  TestInstanceMap,
+  Pick<NodeOptionsMap, 'privy'>,
+  'privy'
+> {
+  constructor() {
+    super()
+    this.register<'privy'>({
+      type: 'privy',
+      validateOptions(options): options is NodeOptionsMap['privy'] {
+        return Boolean((options as NodeOptionsMap['privy'])?.privyClient)
+      },
+      create({ chainManager }, options) {
+        return new PrivyHostedWalletProvider(options.privyClient, chainManager)
+      },
+    })
+  }
+}
+
+describe('HostedWalletProviderRegistry', () => {
+  const mockChainManager = new MockChainManager({
+    supportedChains: [unichain.id],
+  }) as unknown as ChainManager
+  let mockPrivyClient: PrivyClient
+
+  beforeEach(() => {
+    mockPrivyClient = createMockPrivyClient('test-app-id', 'test-app-secret')
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns privy factory and validates options', () => {
+    const registry = new TestHostedWalletProviderRegistry()
+    const factory = registry.getFactory('privy')
+
+    expect(factory.type).toBe('privy')
+    expect(factory.validateOptions?.({ privyClient: mockPrivyClient })).toBe(
+      true,
+    )
+    // Invalid shape should not pass validation
+    expect(factory.validateOptions?.({})).toBe(false)
+  })
+
+  it('creates a PrivyHostedWalletProvider instance', () => {
+    const registry = new TestHostedWalletProviderRegistry()
+    const factory = registry.getFactory('privy')
+
+    const provider = factory.create(
+      { chainManager: mockChainManager },
+      { privyClient: mockPrivyClient },
+    )
+
+    expect(provider).toBeInstanceOf(PrivyHostedWalletProvider)
+  })
+
+  it('throws for unknown provider type', () => {
+    const registry = new TestHostedWalletProviderRegistry()
+    // @ts-expect-error: testing runtime error for unknown type
+    expect(() => registry.getFactory('unknown')).toThrow(
+      'Unknown hosted wallet provider: unknown',
+    )
+  })
+})

package/src/wallet/core/providers/hosted/types/index.ts

@@ -0,0 +1,76 @@
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { LendConfig, LendProvider } from '@/types/lend/index.js'
+import type { HostedWalletProvider } from '@/wallet/core/providers/hosted/abstract/HostedWalletProvider.js'
+
+/**
+ * Common dependencies provided to hosted provider factories
+ * @description
+ * Environment-agnostic services that providers require at creation time.
+ * Currently limited to `ChainManager`, but can be extended as needed.
+ */
+export interface HostedProviderDeps {
+  chainManager: ChainManager
+  lendProvider?: LendProvider<LendConfig>
+}
+
+/**
+ * Provider registration specification
+ * @description
+ * Declarative description of a hosted wallet provider used when registering
+ * a provider factory in a registry.
+ * @template TType Unique provider key (e.g. 'privy', 'turnkey')
+ * @template TConfig Configuration object type for the provider
+ */
+export type ProviderSpec<
+  TType extends string,
+  TConfigMap extends { [K in TType]: unknown | undefined },
+> = {
+  [K in TType]: undefined extends TConfigMap[K]
+    ? { type: K }
+    : { type: K; config: TConfigMap[K] }
+}[TType]
+
+/**
+ * Hosted wallet provider factory
+ * @description
+ * Factory contract used by registries to validate configuration and create
+ * concrete hosted wallet provider instances.
+ * @template TType Unique provider key
+ * @template TInstance Concrete provider instance produced by this factory
+ * @template TOptions Options type accepted by `validateOptions` and `create`
+ */
+export interface HostedProviderFactory<
+  TType extends string,
+  TInstance,
+  TOptions = unknown,
+> {
+  type: TType
+  validateOptions(options: unknown): options is TOptions
+  create(deps: HostedProviderDeps, options: TOptions): TInstance
+}
+
+/**
+ * Complete hosted wallet providers schema (environment-agnostic)
+ * @description
+ * Bundles provider type keys, concrete provider instances, creation configs,
+ * and `toActionsWallet` parameter types for a given environment (Node or React).
+ * This schema enables precise typing in `Actions` and registries without widening
+ * keys to generic `string`.
+ * @template ProviderTypes Union of provider keys for the environment
+ * @template ProviderInstanceMap Map of provider key to concrete instance
+ * @template ProviderConfigMap Map of provider key to factory config type
+ * @template ToActionsOptionsMap Map of provider key to `toActionsWallet` params
+ */
+export type HostedWalletProvidersSchema<
+  ProviderTypes extends string,
+  ProviderInstanceMap extends {
+    [K in ProviderTypes]: HostedWalletProvider<K, ToActionsOptionsMap>
+  },
+  ProviderConfigMap extends { [K in ProviderTypes]: unknown },
+  ToActionsOptionsMap extends { [K in ProviderTypes]: unknown },
+> = {
+  providerTypes: ProviderTypes
+  providerInstances: ProviderInstanceMap
+  providerConfigs: ProviderConfigMap
+  providerToActionsOptions: ToActionsOptionsMap
+}

package/src/wallet/core/providers/smart/abstract/SmartWalletProvider.ts

@@ -0,0 +1,64 @@
+import type { Address, LocalAccount } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { SmartWalletCreationResult } from '@/wallet/core/providers/smart/abstract/types/index.js'
+import type { SmartWallet } from '@/wallet/core/wallets/smart/abstract/SmartWallet.js'
+import type { Signer } from '@/wallet/core/wallets/smart/abstract/types/index.js'
+
+/**
+ * Base smart wallet provider interface
+ * @description Abstract interface for smart wallet providers.
+ */
+export abstract class SmartWalletProvider {
+  /**
+   * Create a new smart wallet instance
+   * @description Creates a new smart wallet and attempts to deploy it across all supported chains.
+   * The wallet address is deterministically calculated from signers and nonce. Deployment failures
+   * on individual chains do not prevent wallet creation - they are reported in the result.
+   * @param params - Wallet creation parameters
+   * @param params.signers - Array of wallet signers
+   * @param params.signer - Local account used for signing transactions
+   * @param params.nonce - Optional nonce for address generation (defaults to 0)
+   * @param params.deploymentChainIds - Optional chain IDs to deploy the wallet to.
+   * If not provided, the wallet will be deployed to all supported chains.
+   * @returns Promise resolving to deployment result containing:
+   * - `wallet`: The created SmartWallet instance
+   * - `deployments`: Array of deployment results with chainId, receipt, success flag, and error
+   */
+  abstract createWallet(params: {
+    signer: LocalAccount
+    signers?: Signer[]
+    nonce?: bigint
+    deploymentChainIds?: SupportedChainId[]
+  }): Promise<SmartWalletCreationResult<SmartWallet>>
+
+  /**
+   * Get an existing smart wallet instance
+   * @description Creates a SmartWallet instance for an already deployed wallet.
+   * Use this when you know the wallet address and want to interact with it.
+   * @param params - Wallet retrieval parameters
+   * @param params.walletAddress - Address of the deployed smart wallet
+   * @param params.signer - Local account used for signing transactions
+   * @param params.signers - Array of wallet signers
+   * @returns SmartWallet instance for the existing wallet
+   */
+  abstract getWallet(params: {
+    walletAddress: Address
+    signer: LocalAccount
+    signers?: Signer[]
+  }): Promise<SmartWallet>
+
+  /**
+   * Get the predicted smart wallet address
+   * @description Calculates the deterministic address where a smart wallet would be deployed
+   * given the specified signers and nonce. Uses CREATE2 for address prediction.
+   * @param params - Address prediction parameters
+   * @param params.signers - Array of wallet signers
+   * @param params.nonce - Nonce for address generation (defaults to 0)
+   * @returns Promise resolving to the predicted wallet address
+   */
+  abstract getWalletAddress(params: {
+    signers: Signer[]
+    nonce?: bigint
+  }): Promise<Address>
+}