@eth-optimism/actions-sdk 0.0.2

package/src/wallet/react/providers/hosted/turnkey/TurnkeyHostedWalletProvider.ts

@@ -0,0 +1,78 @@
+import type { LocalAccount } from 'viem'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { LendConfig, LendProvider } from '@/types/lend/index.js'
+import { HostedWalletProvider } from '@/wallet/core/providers/hosted/abstract/HostedWalletProvider.js'
+import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+import type { ReactToActionsOptionsMap } from '@/wallet/react/providers/hosted/types/index.js'
+import { TurnkeyWallet } from '@/wallet/react/wallets/hosted/turnkey/TurnkeyWallet.js'
+import { createSigner } from '@/wallet/react/wallets/hosted/turnkey/utils/createSigner.js'
+
+/**
+ * Turnkey wallet provider implementation
+ * @description Hosted wallet provider that wraps Turnkey's signing infrastructure
+ * and exposes an Actions-compatible wallet. This provider is intended for browser
+ * environments where the Turnkey client and
+ * organization context are provided at construction time.
+ */
+export class TurnkeyHostedWalletProvider extends HostedWalletProvider<
+  'turnkey',
+  ReactToActionsOptionsMap
+> {
+  /**
+   * Create a new Turnkey wallet provider
+   * @param client - Turnkey browser client instance
+   * @param organizationId - Turnkey organization ID that owns the signing key
+   * @param chainManager - Chain manager used to resolve chains and RPC transports
+   */
+  constructor(
+    chainManager: ChainManager,
+    lendProvider?: LendProvider<LendConfig>,
+  ) {
+    super(chainManager, lendProvider)
+  }
+
+  /**
+   * Convert a Turnkey hosted wallet context into an Actions wallet
+   * @description Creates a `TurnkeyWallet` configured with the provider's Turnkey
+   * client and organization.
+   * @param params - Options for creating the Actions wallet from Turnkey context
+   * @param params.client - Turnkey client instance
+   * @param params.organizationId - Turnkey organization ID that owns the signing key
+   * @param params.signWith - Wallet account address, private key address, or private key ID
+   * @param params.ethereumAddress - Ethereum address to use for this account, in the case that a private key ID is used to sign.
+   * @returns Promise resolving to an Actions-compatible wallet instance
+   */
+  async toActionsWallet(
+    params: ReactToActionsOptionsMap['turnkey'],
+  ): Promise<Wallet> {
+    const { client, organizationId, signWith, ethereumAddress } = params
+    return TurnkeyWallet.create({
+      client,
+      organizationId,
+      signWith,
+      ethereumAddress,
+      chainManager: this.chainManager,
+      lendProvider: this.lendProvider,
+    })
+  }
+
+  /**
+   * Create a viem LocalAccount signer from Turnkey credentials
+   * @description Produces a signing account backed by Turnkey without wrapping
+   * it in a full Actions wallet. This is useful when you need to pass the signer
+   * into an Actions smart wallet as an owner, for lower-level viem operations, or
+   * for passing to other libraries that accept a viem `LocalAccount`.
+   * @param params - Turnkey configuration for the signer
+   * @param params.client - Turnkey client instance
+   * @param params.organizationId - Turnkey organization ID that owns the signing key
+   * @param params.signWith - Wallet account address, private key address, or private key ID
+   * @param params.ethereumAddress - Optional Ethereum address (recommended for passkey clients to avoid extra prompts)
+   * @returns Promise resolving to a viem `LocalAccount` with Turnkey as the signer backend
+   */
+  async createSigner(
+    params: ReactToActionsOptionsMap['turnkey'],
+  ): Promise<LocalAccount> {
+    return createSigner(params)
+  }
+}

package/src/wallet/react/providers/hosted/turnkey/__tests__/TurnkeyHostedWalletProvider.spec.ts

@@ -0,0 +1,142 @@
+import type { TurnkeySDKClientBase } from '@turnkey/react-wallet-kit'
+import type { LocalAccount } from 'viem'
+import { unichain } from 'viem/chains'
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import { MockChainManager } from '@/test/MockChainManager.js'
+import type { LendConfig, LendProvider } from '@/types/lend/index.js'
+import { TurnkeyHostedWalletProvider } from '@/wallet/react/providers/hosted/turnkey/TurnkeyHostedWalletProvider.js'
+import { TurnkeyWallet } from '@/wallet/react/wallets/hosted/turnkey/TurnkeyWallet.js'
+import * as createSignerUtil from '@/wallet/react/wallets/hosted/turnkey/utils/createSigner.js'
+
+describe('TurnkeyHostedWalletProvider', () => {
+  const mockChainManager = new MockChainManager({
+    supportedChains: [unichain.id],
+  }) as unknown as ChainManager
+
+  describe('toActionsWallet', () => {
+    it('forwards params to TurnkeyWallet.create', async () => {
+      const turnkeyClient = {} as unknown as TurnkeySDKClientBase
+      const provider = new TurnkeyHostedWalletProvider(mockChainManager)
+      const spyTurnkeyWalletCreate = vi
+        .spyOn(TurnkeyWallet, 'create')
+        .mockResolvedValueOnce({
+          address: '0xabc',
+        } as unknown as TurnkeyWallet)
+
+      await provider.toActionsWallet({
+        client: turnkeyClient,
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+      })
+
+      expect(spyTurnkeyWalletCreate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          client: turnkeyClient,
+          organizationId: 'org_123',
+          signWith: 'key_abc',
+          ethereumAddress: undefined,
+          chainManager: mockChainManager,
+        }),
+      )
+    })
+
+    it('forwards ethereumAddress when provided', async () => {
+      const turnkeyClient = {} as unknown as TurnkeySDKClientBase
+      const provider = new TurnkeyHostedWalletProvider(mockChainManager)
+      const spyTurnkeyWalletCreate = vi
+        .spyOn(TurnkeyWallet, 'create')
+        .mockResolvedValueOnce({
+          address: '0xabc',
+        } as unknown as TurnkeyWallet)
+
+      await provider.toActionsWallet({
+        client: turnkeyClient,
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+        ethereumAddress: '0x123',
+      })
+
+      expect(spyTurnkeyWalletCreate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          client: turnkeyClient,
+          organizationId: 'org_123',
+          signWith: 'key_abc',
+          ethereumAddress: '0x123',
+          chainManager: mockChainManager,
+        }),
+      )
+    })
+
+    it('returns the created TurnkeyWallet instance', async () => {
+      const turnkeyClient = {} as unknown as TurnkeySDKClientBase
+      const provider = new TurnkeyHostedWalletProvider(mockChainManager)
+      const fakeWallet = {
+        address: '0xabc',
+      } as unknown as TurnkeyWallet
+      vi.spyOn(TurnkeyWallet, 'create').mockResolvedValueOnce(fakeWallet)
+
+      const actionsWallet = await provider.toActionsWallet({
+        client: turnkeyClient,
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+      })
+
+      expect(actionsWallet).toBe(fakeWallet)
+    })
+
+    it('forwards lendProvider when provided to constructor', async () => {
+      const turnkeyClient = {} as unknown as TurnkeySDKClientBase
+      const mockLendProvider = {} as unknown as LendProvider<LendConfig>
+      const provider = new TurnkeyHostedWalletProvider(
+        mockChainManager,
+        mockLendProvider,
+      )
+      const spyTurnkeyWalletCreate = vi
+        .spyOn(TurnkeyWallet, 'create')
+        .mockResolvedValueOnce({
+          address: '0xabc',
+        } as unknown as TurnkeyWallet)
+
+      await provider.toActionsWallet({
+        client: turnkeyClient,
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+      })
+
+      expect(spyTurnkeyWalletCreate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          lendProvider: mockLendProvider,
+        }),
+      )
+    })
+  })
+
+  describe('createSigner', () => {
+    it('should delegate to createSigner utility with correct params', async () => {
+      const provider = new TurnkeyHostedWalletProvider(mockChainManager)
+      const turnkeyClient = {} as unknown as TurnkeySDKClientBase
+
+      const mockSigner = {
+        address: '0xabc',
+        type: 'local',
+      } as unknown as LocalAccount
+
+      const createSignerSpy = vi
+        .spyOn(createSignerUtil, 'createSigner')
+        .mockResolvedValueOnce(mockSigner)
+
+      const params = {
+        client: turnkeyClient,
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+      }
+
+      const signer = await provider.createSigner(params)
+
+      expect(createSignerSpy).toHaveBeenCalledWith(params)
+      expect(signer).toBe(mockSigner)
+    })
+  })
+})

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

@@ -0,0 +1,100 @@
+import type { Wallet as DynamicWallet } from '@dynamic-labs/wallet-connector-core'
+import type { ConnectedWallet } from '@privy-io/react-auth'
+import type { TurnkeySDKClientBase } from '@turnkey/react-wallet-kit'
+
+import type { HostedWalletProvidersSchema } from '@/wallet/core/providers/hosted/types/index.js'
+import type { DynamicHostedWalletProvider } from '@/wallet/react/providers/hosted/dynamic/DynamicHostedWalletProvider.js'
+import type { PrivyHostedWalletProvider } from '@/wallet/react/providers/hosted/privy/PrivyHostedWalletProvider.js'
+import type { TurnkeyHostedWalletProvider } from '@/wallet/react/providers/hosted/turnkey/TurnkeyHostedWalletProvider.js'
+
+/**
+ * React provider type keys
+ * @description
+ * Narrow union of provider identifiers supported in the React/browser environment.
+ * Uses an intersection of the keys from each map to help keep maps in sync
+ * at compile time.
+ */
+export type ReactProviderTypes = keyof ReactOptionsMap &
+  keyof ReactHostedProviderInstanceMap
+
+/**
+ * Configuration options per React hosted wallet provider
+ * @description
+ * Strongly-typed configuration inputs passed to each provider factory when
+ * creating a hosted wallet provider for React. The Dynamic provider has no
+ * build-time options.
+ */
+export interface ReactOptionsMap {
+  dynamic: undefined
+  privy: undefined
+  turnkey: undefined
+}
+
+/**
+ * Options for converting a Dynamic hosted wallet to an Actions wallet
+ * @description Parameters for converting a hosted wallet to an Actions wallet
+ * @property wallet Dynamic wallet instance obtained from the Dynamic connector
+ */
+export type DynamicHostedWalletToActionsWalletOptions = {
+  wallet: DynamicWallet
+}
+
+/**
+ * Options for converting a Privy hosted wallet to an Actions wallet
+ * @description Parameters for converting a Privy hosted wallet to an Actions wallet
+ * @property connectedWallet Privy ConnectedWallet instance from @privy-io/react-auth
+ */
+export type PrivyHostedWalletToActionsWalletOptions = {
+  connectedWallet: ConnectedWallet
+}
+
+/**
+ * Options for converting a Turnkey hosted wallet to an Actions wallet
+ * @description Parameters for converting a hosted wallet to an Actions wallet
+ * @property signWith This can be a wallet account address, private key address, or private key ID.
+ * @property ethereumAddress Ethereum address to use for this account, in the case that a private key ID is used to sign.
+ * If left undefined, `createSigner` will fetch it from the Turnkey API. We recommend setting this if you're using a passkey
+ * client, so that your users are not prompted for a passkey signature just to fetch their address. You may leave this
+ * undefined if using an API key client.
+ */
+export type TurnkeyHostedWalletToActionsWalletOptions = {
+  client: TurnkeySDKClientBase
+  organizationId: string
+  signWith: string
+  ethereumAddress?: string
+}
+
+/**
+ * React/browser hosted wallet registry
+ * @description Registers browser-only providers for client apps.
+ */
+export type ReactHostedProviderInstanceMap = {
+  dynamic: DynamicHostedWalletProvider
+  privy: PrivyHostedWalletProvider
+  turnkey: TurnkeyHostedWalletProvider
+}
+
+/**
+ * Parameters required to convert each hosted wallet to an Actions wallet (React)
+ * @description Provider-specific, caller-supplied data needed by `toActionsWallet`.
+ */
+export type ReactToActionsOptionsMap = {
+  dynamic: DynamicHostedWalletToActionsWalletOptions
+  privy: PrivyHostedWalletToActionsWalletOptions
+  turnkey: TurnkeyHostedWalletToActionsWalletOptions
+}
+
+/**
+ * Complete React hosted wallet providers schema
+ * @description
+ * Bundles provider type keys, concrete provider instances, creation configs,
+ * and `toActionsWallet` parameter types for the React environment.
+ * This schema is used to type `Actions` and its registries without widening
+ * to generic `string` keys.
+ */
+export type ReactHostedWalletProvidersSchema = HostedWalletProvidersSchema<
+  ReactProviderTypes,
+  ReactHostedProviderInstanceMap,
+  ReactOptionsMap,
+  ReactToActionsOptionsMap
+>

package/src/wallet/react/providers/registry/ReactHostedWalletProviderRegistry.ts

@@ -0,0 +1,57 @@
+import { HostedWalletProviderRegistry } from '@/wallet/core/providers/hosted/registry/HostedWalletProviderRegistry.js'
+import { DynamicHostedWalletProvider } from '@/wallet/react/providers/hosted/dynamic/DynamicHostedWalletProvider.js'
+import { PrivyHostedWalletProvider } from '@/wallet/react/providers/hosted/privy/PrivyHostedWalletProvider.js'
+import { TurnkeyHostedWalletProvider } from '@/wallet/react/providers/hosted/turnkey/TurnkeyHostedWalletProvider.js'
+import type {
+  ReactHostedProviderInstanceMap,
+  ReactOptionsMap,
+  ReactProviderTypes,
+} from '@/wallet/react/providers/hosted/types/index.js'
+
+/**
+ * React hosted wallet provider registry
+ * @description
+ * Environment-scoped registry that binds React/browser provider keys to their
+ * factory implementations. This ensures browser-only hosted providers are
+ * discoverable at runtime without importing Node-only code. The registry
+ * pre-registers 'dynamic' and 'privy' providers and can be extended with
+ * additional providers via `register`.
+ */
+export class ReactHostedWalletProviderRegistry extends HostedWalletProviderRegistry<
+  ReactHostedProviderInstanceMap,
+  ReactOptionsMap,
+  ReactProviderTypes
+> {
+  public constructor() {
+    super()
+    this.register<'dynamic'>({
+      type: 'dynamic',
+      validateOptions(_options): _options is ReactOptionsMap['dynamic'] {
+        return true
+      },
+      create({ chainManager, lendProvider }, _options) {
+        return new DynamicHostedWalletProvider(chainManager, lendProvider)
+      },
+    })
+
+    this.register<'privy'>({
+      type: 'privy',
+      validateOptions(_options): _options is ReactOptionsMap['privy'] {
+        return true
+      },
+      create({ chainManager, lendProvider }, _options) {
+        return new PrivyHostedWalletProvider(chainManager, lendProvider)
+      },
+    })
+
+    this.register<'turnkey'>({
+      type: 'turnkey',
+      validateOptions(_options): _options is ReactOptionsMap['turnkey'] {
+        return true
+      },
+      create({ chainManager, lendProvider }, _options) {
+        return new TurnkeyHostedWalletProvider(chainManager, lendProvider)
+      },
+    })
+  }
+}

package/src/wallet/react/providers/registry/__tests__/ReactHostedWalletProviderRegistry.spec.ts

@@ -0,0 +1,117 @@
+import { unichain } from 'viem/chains'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import { MockChainManager } from '@/test/MockChainManager.js'
+import { DynamicHostedWalletProvider } from '@/wallet/react/providers/hosted/dynamic/DynamicHostedWalletProvider.js'
+import { PrivyHostedWalletProvider } from '@/wallet/react/providers/hosted/privy/PrivyHostedWalletProvider.js'
+import { TurnkeyHostedWalletProvider } from '@/wallet/react/providers/hosted/turnkey/TurnkeyHostedWalletProvider.js'
+import type { ReactOptionsMap } from '@/wallet/react/providers/hosted/types/index.js'
+import { ReactHostedWalletProviderRegistry } from '@/wallet/react/providers/registry/ReactHostedWalletProviderRegistry.js'
+
+// Mock the dynamic provider to avoid importing any browser-only dependencies
+vi.mock(
+  '@/wallet/react/providers/hosted/dynamic/DynamicHostedWalletProvider.js',
+  async () => {
+    const { DynamicHostedWalletProviderMock } = await import(
+      '@/wallet/react/providers/hosted/dynamic/__mocks__/DynamicHostedWalletProviderMock.js'
+    )
+    return { DynamicHostedWalletProvider: DynamicHostedWalletProviderMock }
+  },
+)
+
+// Mock the privy provider to avoid importing any browser-only dependencies
+vi.mock(
+  '@/wallet/react/providers/hosted/privy/PrivyHostedWalletProvider.js',
+  async () => {
+    const { PrivyHostedWalletProviderMock } = await import(
+      '@/wallet/react/providers/hosted/privy/__mocks__/PrivyHostedWalletProviderMock.js'
+    )
+    return { PrivyHostedWalletProvider: PrivyHostedWalletProviderMock }
+  },
+)
+
+describe('ReactHostedWalletProviderRegistry', () => {
+  const mockChainManager = new MockChainManager({
+    supportedChains: [unichain.id],
+  }) as unknown as ChainManager
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns dynamic factory and validates options', () => {
+    const registry = new ReactHostedWalletProviderRegistry()
+    const factory = registry.getFactory('dynamic')
+
+    expect(factory.type).toBe('dynamic')
+    // Dynamic options are currently empty; any object should validate to true
+    expect(
+      factory.validateOptions?.(undefined as ReactOptionsMap['dynamic']),
+    ).toBe(true)
+  })
+
+  it('creates a DynamicHostedWalletProvider instance', () => {
+    const registry = new ReactHostedWalletProviderRegistry()
+    const factory = registry.getFactory('dynamic')
+
+    const provider = factory.create(
+      { chainManager: mockChainManager },
+      undefined as ReactOptionsMap['dynamic'],
+    )
+
+    expect(provider).toBeInstanceOf(DynamicHostedWalletProvider)
+  })
+
+  it('returns privy factory and validates options', () => {
+    const registry = new ReactHostedWalletProviderRegistry()
+    const factory = registry.getFactory('privy')
+
+    expect(factory.type).toBe('privy')
+    expect(
+      factory.validateOptions?.(undefined as ReactOptionsMap['privy']),
+    ).toBe(true)
+  })
+
+  it('creates a PrivyHostedWalletProvider instance', () => {
+    const registry = new ReactHostedWalletProviderRegistry()
+    const factory = registry.getFactory('privy')
+
+    const provider = factory.create(
+      { chainManager: mockChainManager },
+      undefined as ReactOptionsMap['privy'],
+    )
+
+    expect(provider).toBeInstanceOf(PrivyHostedWalletProvider)
+  })
+
+  it('returns turnkey factory and validates options', () => {
+    const registry = new ReactHostedWalletProviderRegistry()
+    const factory = registry.getFactory('turnkey')
+
+    expect(factory.type).toBe('turnkey')
+    expect(
+      factory.validateOptions?.(undefined as ReactOptionsMap['turnkey']),
+    ).toBe(true)
+  })
+
+  it('creates a TurnkeyHostedWalletProvider instance', () => {
+    const registry = new ReactHostedWalletProviderRegistry()
+    const factory = registry.getFactory('turnkey')
+
+    const provider = factory.create(
+      { chainManager: mockChainManager },
+      undefined as ReactOptionsMap['turnkey'],
+    )
+
+    expect(provider).toBeInstanceOf(TurnkeyHostedWalletProvider)
+  })
+
+  it('throws for unknown provider type', () => {
+    const registry = new ReactHostedWalletProviderRegistry()
+    // @ts-expect-error: testing runtime error for unknown type
+    expect(() => registry.getFactory('unknown')).toThrow(
+      'Unknown hosted wallet provider: unknown',
+    )
+  })
+})

package/src/wallet/react/wallets/hosted/dynamic/DynamicWallet.ts

@@ -0,0 +1,67 @@
+import { type Address, type LocalAccount } from 'viem'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { LendConfig, LendProvider } from '@/types/lend/index.js'
+import { EOAWallet } from '@/wallet/core/wallets/eoa/EOAWallet.js'
+import type { DynamicHostedWalletToActionsWalletOptions } from '@/wallet/react/providers/hosted/types/index.js'
+import { createSigner } from '@/wallet/react/wallets/hosted/dynamic/utils/createSigner.js'
+
+/**
+ * Dynamic wallet implementation
+ * @description Wallet implementation using the Dynamic Labs wallet SDK.
+ */
+export class DynamicWallet extends EOAWallet {
+  public signer!: LocalAccount
+  public address!: Address
+  private readonly dynamicWallet: DynamicHostedWalletToActionsWalletOptions['wallet']
+
+  /**
+   * Create a new Dynamic wallet
+   * @param chainManager - Chain manager for RPC, chain info, and transports
+   * @param dynamicWallet - Dynamic Labs wallet instance (EVM)
+   */
+  private constructor(
+    chainManager: ChainManager,
+    dynamicWallet: DynamicHostedWalletToActionsWalletOptions['wallet'],
+    lendProvider?: LendProvider<LendConfig>,
+  ) {
+    super(chainManager, lendProvider)
+    this.dynamicWallet = dynamicWallet
+  }
+
+  static async create(params: {
+    dynamicWallet: DynamicHostedWalletToActionsWalletOptions['wallet']
+    chainManager: ChainManager
+    lendProvider?: LendProvider<LendConfig>
+  }): Promise<DynamicWallet> {
+    const wallet = new DynamicWallet(
+      params.chainManager,
+      params.dynamicWallet,
+      params.lendProvider,
+    )
+    await wallet.initialize()
+    return wallet
+  }
+
+  /**
+   * Initialize the DynamicWallet by creating the signer account
+   */
+  protected async performInitialization() {
+    this.signer = await this.createSigner()
+    this.address = this.signer.address
+  }
+
+  /**
+   * Create a LocalAccount from this Dynamic wallet
+   * @description Converts the Dynamic wallet into a viem-compatible LocalAccount that can sign
+   * messages and transactions. The returned account uses Dynamic's signing infrastructure
+   * under the hood while providing a standard viem interface.
+   * @returns Promise resolving to a LocalAccount configured for signing operations
+   * @throws Error if wallet retrieval fails or signing operations are not supported
+   */
+  private async createSigner(): Promise<LocalAccount> {
+    return createSigner({
+      wallet: this.dynamicWallet,
+    })
+  }
+}

package/src/wallet/react/wallets/hosted/dynamic/__mocks__/DynamicWalletMock.ts

@@ -0,0 +1,22 @@
+import { vi } from 'vitest'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+import type { DynamicHostedWalletToActionsWalletOptions } from '@/wallet/react/providers/hosted/types/index.js'
+
+/**
+ * Minimal mock for DynamicWallet used in React tests
+ * @description
+ * Provides a static `create` spy that returns a stubbed `Wallet`, avoiding
+ * browser-only dependencies. Use with `vi.mock` to replace the real module.
+ */
+export class DynamicWalletMock {
+  static readonly create = vi.fn(
+    async (_params: {
+      chainManager: ChainManager
+      dynamicWallet: DynamicHostedWalletToActionsWalletOptions['wallet']
+    }): Promise<Wallet> => {
+      return {} as unknown as Wallet
+    },
+  )
+}