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

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

@@ -0,0 +1,182 @@
+import type { TurnkeyClient } from '@turnkey/http'
+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/node/providers/hosted/turnkey/TurnkeyHostedWalletProvider.js'
+import { TurnkeyWallet } from '@/wallet/node/wallets/hosted/turnkey/TurnkeyWallet.js'
+import * as createSignerUtil from '@/wallet/node/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 TurnkeyClient
+      const provider = new TurnkeyHostedWalletProvider(
+        turnkeyClient,
+        mockChainManager,
+      )
+      const spyTurnkeyWalletCreate = vi
+        .spyOn(TurnkeyWallet, 'create')
+        .mockResolvedValueOnce({
+          address: '0xabc',
+        } as unknown as TurnkeyWallet)
+
+      await provider.toActionsWallet({
+        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 TurnkeyClient
+      const provider = new TurnkeyHostedWalletProvider(
+        turnkeyClient,
+        mockChainManager,
+      )
+      const spyTurnkeyWalletCreate = vi
+        .spyOn(TurnkeyWallet, 'create')
+        .mockResolvedValueOnce({
+          address: '0xabc',
+        } as unknown as TurnkeyWallet)
+
+      await provider.toActionsWallet({
+        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 TurnkeyClient
+      const provider = new TurnkeyHostedWalletProvider(
+        turnkeyClient,
+        mockChainManager,
+      )
+      const fakeWallet = {
+        address: '0xabc',
+      } as unknown as TurnkeyWallet
+      vi.spyOn(TurnkeyWallet, 'create').mockResolvedValueOnce(fakeWallet)
+
+      const actionsWallet = await provider.toActionsWallet({
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+      })
+
+      expect(actionsWallet).toBe(fakeWallet)
+    })
+
+    it('forwards lendProvider when provided to constructor', async () => {
+      const turnkeyClient = {} as unknown as TurnkeyClient
+      const mockLendProvider = {} as LendProvider<LendConfig>
+      const provider = new TurnkeyHostedWalletProvider(
+        turnkeyClient,
+        mockChainManager,
+        mockLendProvider,
+      )
+      const spyTurnkeyWalletCreate = vi
+        .spyOn(TurnkeyWallet, 'create')
+        .mockResolvedValueOnce({
+          address: '0xabc',
+        } as unknown as TurnkeyWallet)
+
+      await provider.toActionsWallet({
+        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 turnkeyClient = {} as unknown as TurnkeyClient
+      const provider = new TurnkeyHostedWalletProvider(
+        turnkeyClient,
+        mockChainManager,
+      )
+      const mockSigner = {
+        address: '0xabc',
+        type: 'local',
+      } as unknown as LocalAccount
+      const createSignerSpy = vi
+        .spyOn(createSignerUtil, 'createSigner')
+        .mockResolvedValueOnce(mockSigner)
+
+      const params = {
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+      }
+
+      const signer = await provider.createSigner(params)
+
+      expect(createSignerSpy).toHaveBeenCalledWith({
+        client: turnkeyClient,
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+      })
+      expect(signer).toBe(mockSigner)
+    })
+
+    it('should forward ethereumAddress when provided', async () => {
+      const turnkeyClient = {} as unknown as TurnkeyClient
+      const provider = new TurnkeyHostedWalletProvider(
+        turnkeyClient,
+        mockChainManager,
+      )
+      const mockSigner = {
+        address: '0x123',
+        type: 'local',
+      } as unknown as LocalAccount
+      const createSignerSpy = vi
+        .spyOn(createSignerUtil, 'createSigner')
+        .mockResolvedValueOnce(mockSigner)
+
+      const params = {
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+        ethereumAddress: '0x123',
+      }
+
+      await provider.createSigner(params)
+
+      expect(createSignerSpy).toHaveBeenCalledWith({
+        client: turnkeyClient,
+        organizationId: 'org_123',
+        signWith: 'key_abc',
+        ethereumAddress: '0x123',
+      })
+    })
+  })
+})

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

@@ -0,0 +1,102 @@
+import type { PrivyClient } from '@privy-io/server-auth'
+import type { TurnkeySDKClientBase } from '@turnkey/core'
+import type { TurnkeyClient as TurnkeyHttpClient } from '@turnkey/http'
+import type { TurnkeyServerClient } from '@turnkey/sdk-server'
+import type { Address } from 'viem'
+
+import type { HostedWalletProvidersSchema } from '@/wallet/core/providers/hosted/types/index.js'
+import type { PrivyHostedWalletProvider } from '@/wallet/node/providers/hosted/privy/PrivyHostedWalletProvider.js'
+import type { TurnkeyHostedWalletProvider } from '@/wallet/node/providers/hosted/turnkey/TurnkeyHostedWalletProvider.js'
+
+/**
+ * Node provider type keys
+ * @description
+ * Narrow union of provider identifiers supported in the Node environment.
+ * Uses an intersection of the keys from each map to guarantee that all maps
+ * stay in sync (options, instances, and toActions options) at compile time.
+ */
+export type NodeProviderTypes = keyof NodeOptionsMap &
+  keyof NodeHostedProviderInstanceMap &
+  keyof NodeToActionsOptionsMap
+
+/**
+ * Configuration options per Node hosted wallet provider
+ * @description
+ * Strongly-typed configuration inputs passed to each provider factory when
+ * creating a hosted wallet provider for Node.
+ */
+export interface NodeOptionsMap {
+  /**
+   * Privy provider configuration
+   * @property privyClient Server-side Privy client instance used to query/create wallets
+   */
+  privy: { privyClient: PrivyClient }
+  /**
+   * Turnkey provider configuration
+   * @property client Turnkey SDK/HTTP client used to sign and manage keys
+   * @property organizationId Turnkey organization identifier that owns the key material
+   */
+  turnkey: {
+    client: TurnkeyHttpClient | TurnkeyServerClient | TurnkeySDKClientBase
+  }
+}
+
+/**
+ * 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, `createAccount` 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 = {
+  organizationId: string
+  signWith: string
+  ethereumAddress?: string
+}
+
+/**
+ * Options for converting a Privy hosted wallet to an Actions wallet
+ * @description Parameters for converting a hosted wallet to an Actions wallet
+ * @property walletId Privy wallet identifier
+ * @property address Ethereum address of the wallet
+ */
+export type PrivyHostedWalletToActionsWalletOptions = {
+  walletId: string
+  address: Address
+}
+
+/**
+ * Node environment hosted wallet registry.
+ * Registers server-safe providers for use in Node.
+ */
+export type NodeHostedProviderInstanceMap = {
+  privy: PrivyHostedWalletProvider
+  turnkey: TurnkeyHostedWalletProvider
+}
+
+/**
+ * Parameters required to convert each hosted wallet to an Actions wallet (Node)
+ * @description
+ * Provider-specific, caller-supplied data needed by `toActionsWallet`.
+ */
+export type NodeToActionsOptionsMap = {
+  privy: PrivyHostedWalletToActionsWalletOptions
+  turnkey: TurnkeyHostedWalletToActionsWalletOptions
+}
+
+/**
+ * Complete Node hosted wallet providers schema
+ * @description
+ * Bundles provider type keys, concrete provider instances, creation configs,
+ * and `toActionsWallet` parameter types for the Node environment.
+ * This schema is used to type `Actions` and its registries without widening
+ * to generic `string` keys.
+ */
+export type NodeHostedWalletProvidersSchema = HostedWalletProvidersSchema<
+  NodeProviderTypes,
+  NodeHostedProviderInstanceMap,
+  NodeOptionsMap,
+  NodeToActionsOptionsMap
+>

package/src/wallet/node/wallets/hosted/privy/PrivyWallet.ts

@@ -0,0 +1,78 @@
+import type { PrivyClient } from '@privy-io/server-auth'
+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 { createSigner } from '@/wallet/node/wallets/hosted/privy/utils/createSigner.js'
+
+/**
+ * Privy wallet implementation
+ * @description Wallet implementation using Privy service
+ */
+export class PrivyWallet extends EOAWallet {
+  public walletId: string
+  public signer!: LocalAccount
+  public readonly address: Address
+  private privyClient: PrivyClient
+
+  /**
+   * Create a new Privy wallet provider
+   * @param appId - Privy application ID
+   * @param appSecret - Privy application secret
+   * @param actions - Actions instance for accessing configured providers
+   */
+  private constructor(
+    privyClient: PrivyClient,
+    walletId: string,
+    address: Address,
+    chainManager: ChainManager,
+    lendProvider?: LendProvider<LendConfig>,
+  ) {
+    super(chainManager, lendProvider)
+    this.privyClient = privyClient
+    this.walletId = walletId
+    this.address = address
+  }
+
+  static async create(params: {
+    privyClient: PrivyClient
+    walletId: string
+    address: Address
+    chainManager: ChainManager
+    lendProvider?: LendProvider<LendConfig>
+  }): Promise<PrivyWallet> {
+    const wallet = new PrivyWallet(
+      params.privyClient,
+      params.walletId,
+      params.address,
+      params.chainManager,
+      params.lendProvider,
+    )
+    await wallet.initialize()
+    return wallet
+  }
+
+  /**
+   * Initialize the PrivyWallet by creating the signer account
+   */
+  protected async performInitialization() {
+    this.signer = await this.createSigner()
+  }
+
+  /**
+   * Create a LocalAccount from this Privy wallet
+   * @description Converts the Privy wallet into a viem-compatible LocalAccount that can sign
+   * messages and transactions. The returned account uses Privy'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({
+      walletId: this.walletId,
+      address: this.address,
+      privyClient: this.privyClient,
+    })
+  }
+}

package/src/wallet/node/wallets/hosted/privy/__tests__/PrivyWallet.spec.ts

@@ -0,0 +1,142 @@
+import type { PrivyClient } from '@privy-io/server-auth'
+import { createViemAccount } from '@privy-io/server-auth/viem'
+import {
+  type Address,
+  createWalletClient,
+  getAddress,
+  type LocalAccount,
+  type WalletClient,
+} 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 { createMockPrivyClient } from '@/test/MockPrivyClient.js'
+import { getRandomAddress } from '@/test/utils.js'
+import { PrivyWallet } from '@/wallet/node/wallets/hosted/privy/PrivyWallet.js'
+
+vi.mock('viem', async () => ({
+  // @ts-ignore - importActual returns unknown
+  ...(await vi.importActual('viem')),
+  createWalletClient: vi.fn(),
+}))
+
+vi.mock('viem/accounts', async () => ({
+  // @ts-ignore - importActual returns unknown
+  ...(await vi.importActual('viem/accounts')),
+  toAccount: vi.fn(),
+}))
+
+vi.mock('@privy-io/server-auth/viem', async () => ({
+  // @ts-ignore - importActual returns unknown
+  ...(await vi.importActual('@privy-io/server-auth/viem')),
+  createViemAccount: vi.fn(),
+}))
+
+const mockAddress = getRandomAddress()
+const mockPrivyClient = createMockPrivyClient('test-app-id', 'test-app-secret')
+const mockChainManager = new MockChainManager({
+  supportedChains: [130], // Unichain
+}) as unknown as ChainManager
+const mockLocalAccount = {
+  address: mockAddress,
+  signMessage: vi.fn(),
+  sign: vi.fn(),
+  signTransaction: vi.fn(),
+  signTypedData: vi.fn(),
+} as unknown as LocalAccount
+
+describe('PrivyWallet', () => {
+  it('should return the correct wallet ID', async () => {
+    const createdWallet = await mockPrivyClient.walletApi.createWallet({
+      chainType: 'ethereum',
+    })
+
+    const wallet = await createAndInitPrivyWallet({
+      address: getAddress(createdWallet.address),
+      walletId: createdWallet.id,
+    })
+
+    expect(wallet.walletId).toBe(createdWallet.id)
+  })
+
+  it('should return the correct address', async () => {
+    const createdWallet = await mockPrivyClient.walletApi.createWallet({
+      chainType: 'ethereum',
+    })
+
+    const wallet = await createAndInitPrivyWallet({
+      address: getAddress(createdWallet.address),
+      walletId: createdWallet.id,
+    })
+
+    expect(wallet.address).toBe(createdWallet.address)
+  })
+
+  it('should create an account with correct configuration', async () => {
+    // Create a wallet using the mock client first
+    const createdWallet = await mockPrivyClient.walletApi.createWallet({
+      chainType: 'ethereum',
+    })
+    vi.mocked(createViemAccount).mockResolvedValue(mockLocalAccount)
+    const wallet = await createAndInitPrivyWallet({
+      address: getAddress(createdWallet.address),
+      walletId: createdWallet.id,
+    })
+
+    expect(createViemAccount).toHaveBeenCalledWith({
+      walletId: createdWallet.id,
+      address: createdWallet.address,
+      privy: mockPrivyClient,
+    })
+    expect(wallet.signer).toBe(mockLocalAccount)
+  })
+
+  it('should create a wallet client with correct configuration', async () => {
+    const createdWallet = await mockPrivyClient.walletApi.createWallet({
+      chainType: 'ethereum',
+    })
+    const wallet = await createAndInitPrivyWallet()
+
+    const mockWalletClient = {
+      account: mockLocalAccount,
+      address: createdWallet.address as Address,
+    } as unknown as WalletClient
+    vi.mocked(createViemAccount).mockResolvedValue(mockLocalAccount)
+    vi.mocked(createWalletClient).mockResolvedValue(mockWalletClient)
+
+    const walletClient = await wallet.walletClient(unichain.id)
+
+    expect(createWalletClient).toHaveBeenCalledOnce()
+    const callArgs = vi.mocked(createWalletClient).mock.calls[0][0]
+    expect(callArgs.account).toBe(mockLocalAccount)
+    expect(callArgs.chain).toBe(mockChainManager.getChain(unichain.id))
+    expect(walletClient).toBe(mockWalletClient)
+  })
+})
+
+async function createAndInitPrivyWallet(
+  params: {
+    privyClient?: PrivyClient
+    walletId?: string
+    address?: Address
+    chainManager?: ChainManager
+  } = {},
+) {
+  const {
+    privyClient = mockPrivyClient,
+    walletId,
+    address,
+    chainManager = mockChainManager,
+  } = params
+  const createdWallet = await privyClient.walletApi.createWallet({
+    chainType: 'ethereum',
+  })
+  return PrivyWallet.create({
+    privyClient,
+    walletId: walletId ?? createdWallet.id,
+    address: address ?? getAddress(createdWallet.address),
+    chainManager,
+  })
+}

package/src/wallet/node/wallets/hosted/privy/utils/__tests__/createSigner.spec.ts

@@ -0,0 +1,48 @@
+import { createViemAccount } from '@privy-io/server-auth/viem'
+import type { Address, LocalAccount } from 'viem'
+import { describe, expect, it, vi } from 'vitest'
+
+import { createMockPrivyClient } from '@/test/MockPrivyClient.js'
+import { getRandomAddress } from '@/test/utils.js'
+import { createSigner } from '@/wallet/node/wallets/hosted/privy/utils/createSigner.js'
+
+vi.mock('@privy-io/server-auth/viem', async () => ({
+  // @ts-ignore - importActual returns unknown
+  ...(await vi.importActual('@privy-io/server-auth/viem')),
+  createViemAccount: vi.fn(),
+}))
+
+describe('createSigner (Node Privy)', () => {
+  const mockAddress = getRandomAddress()
+  const mockPrivyClient = createMockPrivyClient(
+    'test-app-id',
+    'test-app-secret',
+  )
+  const mockLocalAccount = {
+    address: mockAddress,
+    signMessage: vi.fn(),
+    sign: vi.fn(),
+    signTransaction: vi.fn(),
+    signTypedData: vi.fn(),
+  } as unknown as LocalAccount
+
+  it('should create a LocalAccount with correct configuration', async () => {
+    const createdWallet = await mockPrivyClient.walletApi.createWallet({
+      chainType: 'ethereum',
+    })
+    vi.mocked(createViemAccount).mockResolvedValue(mockLocalAccount)
+
+    const signer = await createSigner({
+      privyClient: mockPrivyClient,
+      walletId: createdWallet.id,
+      address: createdWallet.address as Address,
+    })
+
+    expect(createViemAccount).toHaveBeenCalledWith({
+      walletId: createdWallet.id,
+      address: createdWallet.address,
+      privy: mockPrivyClient,
+    })
+    expect(signer).toBe(mockLocalAccount)
+  })
+})

package/src/wallet/node/wallets/hosted/privy/utils/createSigner.ts

@@ -0,0 +1,32 @@
+import type { GetViemAccountInputType } from '@privy-io/server-auth/viem'
+import { createViemAccount } from '@privy-io/server-auth/viem'
+import type { LocalAccount } from 'viem'
+
+import type {
+  NodeOptionsMap,
+  PrivyHostedWalletToActionsWalletOptions,
+} from '@/wallet/node/providers/hosted/types/index.js'
+
+/**
+ * Create a LocalAccount from a Privy wallet
+ * @description Converts the Privy wallet into a viem-compatible LocalAccount that can sign
+ * messages and transactions. The returned account uses Privy's signing infrastructure
+ * under the hood while providing a standard viem interface.
+ * @param params.walletId - Privy wallet identifier
+ * @param params.address - Ethereum address of the wallet
+ * @param params.privyClient - Privy client instance
+ * @returns Promise resolving to a LocalAccount configured for signing operations
+ * @throws Error if wallet retrieval fails or signing operations are not supported
+ */
+export async function createSigner(
+  params: PrivyHostedWalletToActionsWalletOptions & NodeOptionsMap['privy'],
+): Promise<LocalAccount> {
+  const { walletId, address, privyClient } = params
+  const account = await createViemAccount({
+    walletId,
+    address,
+    // TODO: Fix this type error
+    privy: privyClient as unknown as GetViemAccountInputType['privy'],
+  })
+  return account
+}

package/src/wallet/node/wallets/hosted/turnkey/TurnkeyWallet.ts

@@ -0,0 +1,90 @@
+import type { TurnkeySDKClientBase } from '@turnkey/core'
+import type { TurnkeyClient } from '@turnkey/http'
+import type { TurnkeyServerClient } from '@turnkey/sdk-server'
+import type { Address, 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 { createSigner } from '@/wallet/node/wallets/hosted/turnkey/utils/createSigner.js'
+
+/**
+ * Turnkey wallet implementation
+ * @description Wallet implementation using Turnkey service
+ */
+export class TurnkeyWallet extends EOAWallet {
+  public address!: Address
+  public signer!: LocalAccount
+  /**
+   * Turnkey client instance (HTTP, server, or core SDK base)
+   */
+  private readonly client:
+    | TurnkeyClient
+    | TurnkeyServerClient
+    | TurnkeySDKClientBase
+  /**
+   * Turnkey organization ID that owns the signing key
+   */
+  private readonly organizationId: string
+  /**
+   * This can be a wallet account address, private key address, or private key ID.
+   */
+  private readonly signWith: string
+  /**
+   * Ethereum address to use for this account, in the case that a private key ID is used to sign.
+   * If left undefined, `createAccount` 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.
+   */
+  private readonly ethereumAddress?: string
+
+  private constructor(params: {
+    chainManager: ChainManager
+    client: TurnkeyClient | TurnkeyServerClient | TurnkeySDKClientBase
+    organizationId: string
+    signWith: string
+    ethereumAddress?: string
+    lendProvider?: LendProvider<LendConfig>
+  }) {
+    const {
+      chainManager,
+      client,
+      organizationId,
+      signWith,
+      ethereumAddress,
+      lendProvider,
+    } = params
+    super(chainManager, lendProvider)
+    this.client = client
+    this.organizationId = organizationId
+    this.signWith = signWith
+    this.ethereumAddress = ethereumAddress
+  }
+
+  static async create(params: {
+    chainManager: ChainManager
+    client: TurnkeyClient | TurnkeyServerClient | TurnkeySDKClientBase
+    organizationId: string
+    signWith: string
+    ethereumAddress?: string
+    lendProvider?: LendProvider<LendConfig>
+  }): Promise<TurnkeyWallet> {
+    const wallet = new TurnkeyWallet(params)
+    await wallet.initialize()
+    return wallet
+  }
+
+  protected async performInitialization() {
+    this.signer = await this.createSigner()
+    this.address = this.signer.address
+  }
+
+  private async createSigner(): Promise<LocalAccount> {
+    return createSigner({
+      client: this.client,
+      organizationId: this.organizationId,
+      signWith: this.signWith,
+      ethereumAddress: this.ethereumAddress,
+    })
+  }
+}