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

package/src/wallet/core/wallets/eoa/__tests__/EOAWallet.spec.ts

@@ -0,0 +1,299 @@
+import type {
+  Address,
+  Chain,
+  Hex,
+  LocalAccount,
+  PublicClient,
+  WalletClient,
+} from 'viem'
+import { createWalletClient } from 'viem'
+import { unichain } from 'viem/chains'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import { MockChainManager } from '@/test/MockChainManager.js'
+import { getRandomAddress } from '@/test/utils.js'
+import type { TransactionData } from '@/types/lend/index.js'
+import type { EOATransactionReceipt } from '@/wallet/core/wallets/abstract/types/index.js'
+import { EOAWallet } from '@/wallet/core/wallets/eoa/EOAWallet.js'
+
+vi.mock('viem', async () => ({
+  // @ts-ignore - importActual returns unknown
+  ...(await vi.importActual('viem')),
+  createWalletClient: vi.fn(),
+}))
+
+// Concrete implementation for testing abstract class
+class TestEOAWallet extends EOAWallet {
+  public readonly address: Address
+  public readonly signer: LocalAccount
+
+  constructor(
+    address: Address,
+    signer: LocalAccount,
+    chainManager: ChainManager,
+  ) {
+    super(chainManager)
+    this.address = address
+    this.signer = signer
+  }
+
+  static async create(
+    address: Address,
+    signer: LocalAccount,
+    chainManager: ChainManager,
+  ): Promise<TestEOAWallet> {
+    const wallet = new TestEOAWallet(address, signer, chainManager)
+    await wallet.initialize()
+    return wallet
+  }
+}
+
+const mockAddress = getRandomAddress()
+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
+
+const mockTransactionHash: Hex =
+  '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+
+const mockReceipt: EOATransactionReceipt = {
+  transactionHash: mockTransactionHash,
+  blockNumber: 12345n,
+  status: 'success',
+  from: mockAddress,
+  to: getRandomAddress(),
+  gasUsed: 21000n,
+} as EOATransactionReceipt
+
+describe('EOAWallet', () => {
+  let wallet: TestEOAWallet
+  let mockWalletClient: WalletClient
+  let mockPublicClient: PublicClient
+
+  beforeEach(async () => {
+    vi.clearAllMocks()
+
+    // Setup mock wallet client
+    mockWalletClient = {
+      sendTransaction: vi.fn().mockResolvedValue(mockTransactionHash),
+    } as unknown as WalletClient
+
+    // Setup mock public client
+    mockPublicClient = {
+      waitForTransactionReceipt: vi.fn().mockResolvedValue(mockReceipt),
+    } as unknown as PublicClient
+
+    // Mock chainManager methods
+    vi.spyOn(mockChainManager, 'getChain').mockReturnValue(
+      unichain as unknown as Chain,
+    )
+    vi.spyOn(mockChainManager, 'getRpcUrls').mockReturnValue([
+      'https://rpc1.example.com',
+      'https://rpc2.example.com',
+    ])
+    vi.spyOn(mockChainManager, 'getPublicClient').mockReturnValue(
+      mockPublicClient,
+    )
+
+    // Mock createWalletClient
+    vi.mocked(createWalletClient).mockResolvedValue(mockWalletClient)
+
+    wallet = await TestEOAWallet.create(
+      mockAddress,
+      mockLocalAccount,
+      mockChainManager,
+    )
+  })
+
+  describe('walletClient', () => {
+    it('should create a wallet client with correct configuration', async () => {
+      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(unichain)
+      expect(walletClient).toBe(mockWalletClient)
+    })
+  })
+
+  describe('send', () => {
+    const mockTransactionData: TransactionData = {
+      to: getRandomAddress(),
+      value: 1000000000000000000n, // 1 ETH
+      data: '0x',
+    }
+
+    it('should send a transaction and return receipt', async () => {
+      const receipt = await wallet.send(mockTransactionData, unichain.id)
+
+      expect(mockWalletClient.sendTransaction).toHaveBeenCalledWith(
+        mockTransactionData,
+      )
+      expect(mockChainManager.getPublicClient).toHaveBeenCalledWith(unichain.id)
+      expect(mockPublicClient.waitForTransactionReceipt).toHaveBeenCalledWith({
+        hash: mockTransactionHash,
+      })
+      expect(receipt).toBe(mockReceipt)
+    })
+
+    it('should create wallet client with correct chain', async () => {
+      await wallet.send(mockTransactionData, unichain.id)
+
+      expect(mockChainManager.getChain).toHaveBeenCalledWith(unichain.id)
+      expect(createWalletClient).toHaveBeenCalled()
+    })
+  })
+
+  describe('sendBatch', () => {
+    const mockTransactionData1: TransactionData = {
+      to: getRandomAddress(),
+      value: 1000000000000000000n,
+      data: '0x',
+    }
+
+    const mockTransactionData2: TransactionData = {
+      to: getRandomAddress(),
+      value: 2000000000000000000n,
+      data: '0xabcd',
+    }
+
+    const mockTransactionData3: TransactionData = {
+      to: getRandomAddress(),
+      value: 3000000000000000000n,
+      data: '0x1234',
+    }
+
+    const mockReceipt2: EOATransactionReceipt = {
+      ...mockReceipt,
+      transactionHash:
+        '0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Hex,
+    }
+
+    const mockReceipt3: EOATransactionReceipt = {
+      ...mockReceipt,
+      transactionHash:
+        '0x9876543210987654321098765432109876543210987654321098765432109876' as Hex,
+    }
+
+    beforeEach(() => {
+      vi.mocked(mockWalletClient.sendTransaction)
+        .mockResolvedValueOnce(mockReceipt.transactionHash)
+        .mockResolvedValueOnce(mockReceipt2.transactionHash)
+        .mockResolvedValueOnce(mockReceipt3.transactionHash)
+
+      vi.mocked(mockPublicClient.waitForTransactionReceipt)
+        .mockResolvedValueOnce(mockReceipt)
+        .mockResolvedValueOnce(mockReceipt)
+        .mockResolvedValueOnce(mockReceipt2)
+        .mockResolvedValueOnce(mockReceipt2)
+        .mockResolvedValueOnce(mockReceipt3)
+        .mockResolvedValueOnce(mockReceipt3)
+    })
+
+    it('should send multiple transactions sequentially', async () => {
+      const receipts = await wallet.sendBatch(
+        [mockTransactionData1, mockTransactionData2, mockTransactionData3],
+        unichain.id,
+      )
+
+      expect(receipts).toHaveLength(3)
+      expect(receipts[0]).toBe(mockReceipt)
+      expect(receipts[1]).toBe(mockReceipt2)
+      expect(receipts[2]).toBe(mockReceipt3)
+
+      expect(mockWalletClient.sendTransaction).toHaveBeenCalledTimes(3)
+      expect(mockWalletClient.sendTransaction).toHaveBeenNthCalledWith(
+        1,
+        mockTransactionData1,
+      )
+      expect(mockWalletClient.sendTransaction).toHaveBeenNthCalledWith(
+        2,
+        mockTransactionData2,
+      )
+      expect(mockWalletClient.sendTransaction).toHaveBeenNthCalledWith(
+        3,
+        mockTransactionData3,
+      )
+    })
+
+    it('should wait for extra confirmations after each transaction', async () => {
+      await wallet.sendBatch(
+        [mockTransactionData1, mockTransactionData2],
+        unichain.id,
+      )
+
+      // Should be called twice per transaction:
+      // 1. Initial wait in send()
+      // 2. Extra confirmation wait (confirmations: 2) in sendBatch()
+      expect(mockPublicClient.waitForTransactionReceipt).toHaveBeenCalledTimes(
+        4,
+      )
+
+      // Check that extra confirmation wait was called with confirmations: 2
+      expect(
+        mockPublicClient.waitForTransactionReceipt,
+      ).toHaveBeenNthCalledWith(2, {
+        hash: mockReceipt.transactionHash,
+        confirmations: 2,
+      })
+
+      expect(
+        mockPublicClient.waitForTransactionReceipt,
+      ).toHaveBeenNthCalledWith(4, {
+        hash: mockReceipt2.transactionHash,
+        confirmations: 2,
+      })
+    })
+
+    it('should get public client for each transaction', async () => {
+      await wallet.sendBatch(
+        [mockTransactionData1, mockTransactionData2],
+        unichain.id,
+      )
+
+      // Called twice per transaction (once in send, once for extra confirmation)
+      expect(mockChainManager.getPublicClient).toHaveBeenCalledTimes(4)
+      expect(mockChainManager.getPublicClient).toHaveBeenCalledWith(unichain.id)
+    })
+
+    it('should handle single transaction in batch', async () => {
+      const receipts = await wallet.sendBatch(
+        [mockTransactionData1],
+        unichain.id,
+      )
+
+      expect(receipts).toHaveLength(1)
+      expect(receipts[0]).toBe(mockReceipt)
+      expect(mockWalletClient.sendTransaction).toHaveBeenCalledOnce()
+    })
+
+    it('should return empty array for empty batch', async () => {
+      const receipts = await wallet.sendBatch([], unichain.id)
+
+      expect(receipts).toEqual([])
+      expect(mockWalletClient.sendTransaction).not.toHaveBeenCalled()
+    })
+
+    it('should maintain transaction order in results', async () => {
+      const receipts = await wallet.sendBatch(
+        [mockTransactionData1, mockTransactionData2, mockTransactionData3],
+        unichain.id,
+      )
+
+      // Verify order is preserved
+      expect(receipts[0].transactionHash).toBe(mockReceipt.transactionHash)
+      expect(receipts[1].transactionHash).toBe(mockReceipt2.transactionHash)
+      expect(receipts[2].transactionHash).toBe(mockReceipt3.transactionHash)
+    })
+  })
+})

package/src/wallet/core/wallets/smart/abstract/SmartWallet.ts

@@ -0,0 +1,93 @@
+import type { Address } from 'viem'
+import type { WaitForUserOperationReceiptReturnType } from 'viem/account-abstraction'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { Asset } from '@/types/asset.js'
+import type { TransactionData } from '@/types/lend/index.js'
+import { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+import type { Signer } from '@/wallet/core/wallets/smart/abstract/types/index.js'
+
+/**
+ * Base smart wallet class
+ * @description Abstract base class for smart wallet implementations (ERC-4337 compatible wallets).
+ */
+export abstract class SmartWallet extends Wallet {
+  /**
+   * Send a transaction using this smart wallet
+   * @description Executes a transaction through the smart wallet, handling gas sponsorship
+   * and ERC-4337 UserOperation creation automatically.
+   * @param transactionData - The transaction data to execute
+   * @param chainId - Target blockchain chain ID
+   * @returns Promise resolving to the transaction hash
+   */
+  abstract send(
+    transactionData: TransactionData,
+    chainId: SupportedChainId,
+  ): Promise<WaitForUserOperationReceiptReturnType>
+
+  /**
+   * Send a batch of transactions using this smart wallet
+   * @description Executes a batch of transactions through the smart wallet, handling gas sponsorship
+   * and ERC-4337 UserOperation creation automatically.
+   * @param transactionData - The transaction data to execute
+   * @param chainId
+   */
+  abstract sendBatch(
+    transactionData: TransactionData[],
+    chainId: SupportedChainId,
+  ): Promise<WaitForUserOperationReceiptReturnType>
+
+  /**
+   * Add a new signer to the smart wallet
+   * @description Adds either an EOA address signer or a WebAuthn account signer
+   * to the underlying smart wallet contract.
+   * @param signer - Ethereum address (EOA) or a `WebAuthnAccount` to add
+   * @param chainId - Target chain on which the smart wallet operates
+   * @returns Promise resolving to the onchain signer index for the newly added signer
+   * @throws Error if the add operation fails or the owner index cannot be found
+   */
+  abstract addSigner(signer: Signer, chainId: SupportedChainId): Promise<number>
+
+  /**
+   * Remove a signer from the smart wallet
+   * @param signer - Ethereum address (EOA) or a `WebAuthnAccount` to remove
+   * @param chainId - Target chain on which the smart wallet operates
+   * @param signerIndex - Index of the signer to remove, if not provided, it will be found by
+   * doing a lookup on the smart wallet contract.
+   * @returns Promise resolving to the receipt of the remove operation
+   */
+  abstract removeSigner(
+    signer: Signer,
+    chainId: SupportedChainId,
+    signerIndex?: number,
+  ): Promise<WaitForUserOperationReceiptReturnType>
+
+  /**
+   * Find the index of a signer in the smart wallet
+   * @param signer - Ethereum address (EOA) or a `WebAuthnAccount` to find
+   * @param chainId - Target chain on which the smart wallet operates
+   * @returns Promise resolving to the onchain signer index for the found signer
+   * returns -1 if the signer is not found
+   */
+  abstract findSignerIndexOnChain(
+    signer: Signer,
+    chainId: SupportedChainId,
+  ): Promise<number>
+
+  /**
+   * Send tokens to another address
+   * @description Prepares transaction data for sending tokens from this smart wallet
+   * to a recipient address. Returns transaction data that can be executed via send().
+   * @param amount - Amount to send in human-readable format
+   * @param asset - Asset object with address mapping and metadata
+   * @param chainId - Chain ID for the transaction
+   * @param recipientAddress - Destination address for the tokens
+   * @returns Promise resolving to prepared transaction data
+   */
+  abstract sendTokens(
+    amount: number,
+    asset: Asset,
+    chainId: SupportedChainId,
+    recipientAddress: Address,
+  ): Promise<TransactionData>
+}

package/src/wallet/core/wallets/smart/abstract/__mocks__/SmartWallet.ts

@@ -0,0 +1,161 @@
+import type { Address, Hex, LocalAccount, WalletClient } from 'viem'
+import type { WaitForUserOperationReceiptReturnType } from 'viem/account-abstraction'
+import { vi } from 'vitest'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { Asset } from '@/types/asset.js'
+import type { TransactionData } from '@/types/lend/index.js'
+import type { SmartWallet } from '@/wallet/core/wallets/smart/abstract/SmartWallet.js'
+
+export type CreateSmartWalletMockOptions = {
+  /** Mock wallet address */
+  address?: Address
+  /** Mock signer */
+  signer?: LocalAccount
+  /** Custom implementation for addSigner */
+  addSignerImpl?: (
+    owner: Address | { type: 'webAuthn'; publicKey: Hex },
+    chainId: SupportedChainId,
+  ) => Promise<number | void>
+  /** Custom implementation for findSignerIndex */
+  findSignerIndexImpl?: (
+    signer: Address | { type: 'webAuthn'; publicKey: Hex },
+    chainId: SupportedChainId,
+  ) => Promise<number>
+  /** Custom implementation for removeSigner */
+  removeSignerImpl?: (
+    signer: Address | { type: 'webAuthn'; publicKey: Hex },
+    chainId: SupportedChainId,
+    signerIndex?: number,
+  ) => Promise<WaitForUserOperationReceiptReturnType>
+  /** Custom implementation for send */
+  sendImpl?: (
+    transactionData: TransactionData,
+    chainId: SupportedChainId,
+  ) => Promise<WaitForUserOperationReceiptReturnType>
+  /** Custom implementation for sendBatch */
+  sendBatchImpl?: (
+    transactionData: TransactionData[],
+    chainId: SupportedChainId,
+  ) => Promise<WaitForUserOperationReceiptReturnType>
+  /** Optional custom walletClient implementation */
+  walletClientImpl?: (chainId: SupportedChainId) => Promise<WalletClient>
+  /** Optional custom sendTokens implementation */
+  sendTokensImpl?: (
+    amount: number,
+    asset: Asset,
+    chainId: SupportedChainId,
+    recipientAddress: Address,
+  ) => Promise<TransactionData>
+}
+
+/**
+ * Create a mock SmartWallet instance
+ * @description Returns an object typed as `SmartWallet` with configurable
+ * implementations for `send` and `sendBatch`. Other abstract members are
+ * provided with minimal defaults or throw if invoked (unless overridden).
+ */
+export function createMock(
+  options: CreateSmartWalletMockOptions = {},
+): SmartWallet {
+  const defaultReceipt = {
+    success: true,
+  } as unknown as WaitForUserOperationReceiptReturnType
+
+  const address: Address = (options.address ??
+    '0x0000000000000000000000000000000000000000') as Address
+  const signer: LocalAccount =
+    options.signer ?? ({ address, type: 'local' } as unknown as LocalAccount)
+
+  const addSigner = vi.fn(
+    async (
+      owner: Address | { type: 'webAuthn'; publicKey: Hex },
+      chainId: SupportedChainId,
+    ): Promise<number | void> => {
+      if (options.addSignerImpl) return options.addSignerImpl(owner, chainId)
+      return undefined
+    },
+  )
+
+  const findSignerIndex = vi.fn(
+    async (
+      signer: Address | { type: 'webAuthn'; publicKey: Hex },
+      chainId: SupportedChainId,
+    ): Promise<number> => {
+      if (options.findSignerIndexImpl)
+        return options.findSignerIndexImpl(signer, chainId)
+      return -1
+    },
+  )
+
+  const removeSigner = vi.fn(
+    async (
+      signer: Address | { type: 'webAuthn'; publicKey: Hex },
+      chainId: SupportedChainId,
+      signerIndex?: number,
+    ): Promise<WaitForUserOperationReceiptReturnType> => {
+      if (options.removeSignerImpl)
+        return options.removeSignerImpl(signer, chainId, signerIndex)
+      return defaultReceipt
+    },
+  )
+
+  const send = vi.fn(
+    async (
+      transactionData: TransactionData,
+      chainId: SupportedChainId,
+    ): Promise<WaitForUserOperationReceiptReturnType> => {
+      if (options.sendImpl) return options.sendImpl(transactionData, chainId)
+      return defaultReceipt
+    },
+  )
+
+  const sendBatch = vi.fn(
+    async (
+      transactionData: TransactionData[],
+      chainId: SupportedChainId,
+    ): Promise<WaitForUserOperationReceiptReturnType> => {
+      if (options.sendBatchImpl)
+        return options.sendBatchImpl(transactionData, chainId)
+      return defaultReceipt
+    },
+  )
+
+  const walletClient = vi.fn(
+    async (chainId: SupportedChainId): Promise<WalletClient> => {
+      if (options.walletClientImpl) return options.walletClientImpl(chainId)
+      throw new Error('walletClient not implemented in SmartWallet mock')
+    },
+  )
+
+  const sendTokens = vi.fn(
+    async (
+      amount: number,
+      asset: Asset,
+      chainId: SupportedChainId,
+      recipientAddress: Address,
+    ): Promise<TransactionData> => {
+      if (options.sendTokensImpl)
+        return options.sendTokensImpl(amount, asset, chainId, recipientAddress)
+      throw new Error('sendTokens not implemented in SmartWallet mock')
+    },
+  )
+
+  const mock = {
+    get address() {
+      return address
+    },
+    get signer() {
+      return signer
+    },
+    addSigner,
+    findSignerIndex,
+    removeSigner,
+    walletClient,
+    send,
+    sendBatch,
+    sendTokens,
+  } as unknown as SmartWallet
+
+  return mock
+}

package/src/wallet/core/wallets/smart/abstract/types/index.ts

@@ -0,0 +1,19 @@
+import type { Address, LocalAccount, OneOf } from 'viem'
+import type { WebAuthnAccount } from 'viem/account-abstraction'
+
+/**
+ * A single signer/owner for a Smart Wallet.
+ *
+ * Can be one of three types:
+ * - **`Address`**: A plain Ethereum address (hex string like `'0x123...'`). The address itself cannot sign,
+ * but can be used as an owner identifier.
+ * - **`LocalAccount`**: A local account (e.g., from a private key or mnemonic) that can sign transactions
+ * and messages using standard ECDSA signatures.
+ * - **`WebAuthnAccount`**: A WebAuthn/passkey account that signs using the WebAuthn P256 curve,
+ * typically used for biometric authentication.
+ *
+ * The `OneOf` utility ensures that account objects are mutually exclusive - an account can be
+ * either a `LocalAccount` OR a `WebAuthnAccount`, never a hybrid with properties from both types.
+ * This prevents type confusion and ensures proper signature handling for each account type.
+ */
+export type Signer = Address | OneOf<LocalAccount | WebAuthnAccount>