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

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

@@ -0,0 +1,149 @@
+import type { Address, LocalAccount } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { WalletLendNamespace } from '@/lend/namespaces/WalletLendNamespace.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import { fetchERC20Balance, fetchETHBalance } from '@/services/tokenBalance.js'
+import { SUPPORTED_TOKENS } from '@/supported/tokens.js'
+import type { TokenBalance } from '@/types/asset.js'
+import type {
+  BaseLendConfig,
+  LendConfig,
+  LendProvider,
+  TransactionData,
+} from '@/types/lend/index.js'
+import type {
+  BatchTransactionReturnType,
+  TransactionReturnType,
+} from '@/wallet/core/wallets/abstract/types/index.js'
+
+/**
+ * Base actions wallet class
+ * @description Abstract base class for actions wallet implementations.
+ * Provides a standard interface for actions wallets.
+ */
+export abstract class Wallet {
+  /** Lend namespace with all lending operations */
+  lend?: WalletLendNamespace<BaseLendConfig>
+  /** Provider for lending market operations */
+  protected lendProvider?: LendProvider<LendConfig>
+  /** Manages supported blockchain networks and RPC clients */
+  protected chainManager: ChainManager
+  /** Promise to initialize the wallet */
+  private initPromise?: Promise<void>
+
+  /**
+   * Get the address of this actions wallet
+   * @description Returns the address of the actions wallet.
+   * @returns The address of the actions wallet.
+   */
+  public abstract readonly address: Address
+  /**
+   * Get a signer for this actions wallet
+   * @description Returns a LocalAccount that can be used to sign transactions and messages.
+   * This can be used as the signer for smart wallet operations if the signer is an
+   * owner on the smart wallet.
+   * @returns Promise resolving to a LocalAccount configured for signing operations
+   */
+  public abstract readonly signer: LocalAccount
+
+  /**
+   * Create a new wallet
+   * @param chainManager - Chain manager for the wallet
+   * @param lendProvider - Lend provider for the wallet
+   */
+  protected constructor(
+    chainManager: ChainManager,
+    lendProvider?: LendProvider<LendConfig>,
+  ) {
+    this.chainManager = chainManager
+    this.lendProvider = lendProvider
+    if (this.lendProvider) {
+      this.lend = new WalletLendNamespace(this.lendProvider, this)
+    }
+  }
+
+  /**
+   * Get asset balances across all supported chains
+   * @description Fetches ETH and ERC20 token balances for this wallet across all supported networks.
+   * @returns Promise resolving to array of token balances with chain breakdown
+   */
+  async getBalance(): Promise<TokenBalance[]> {
+    // TEMPORARY - will use optimism token list eventually
+    const tokenBalancePromises = SUPPORTED_TOKENS.map(async (asset) => {
+      return fetchERC20Balance(this.chainManager, this.address, asset)
+    })
+    const ethBalancePromise = fetchETHBalance(this.chainManager, this.address)
+
+    return Promise.all([ethBalancePromise, ...tokenBalancePromises])
+  }
+
+  /**
+   * Perform subclass-specific one-time initialization
+   * @description Hook for concrete wallet implementations to perform their
+   * required setup (e.g., compute and cache address, create signer/account,
+   * warm caches). This method is invoked by {@link initialize} and should not
+   * be called directly by consumers.
+   *
+   * Implementations should set all internal state required for public methods
+   * to operate safely after initialization completes, and should throw on
+   * failure so {@link initialize} can surface the error to callers.
+   *
+   * Note: This hook is expected to be idempotent in effect when called via
+   * {@link initialize}, which guarantees concurrency-safety and ensures it is
+   * executed at most once per instance.
+   * @returns Promise that resolves when initialization work is complete
+   */
+  protected async performInitialization(): Promise<void> {}
+
+  /**
+   * Initialize the wallet (idempotent and concurrency-safe)
+   * @description Public-facing initialization entrypoint used internally by
+   * factories/providers and defensively by public methods. If initialization is
+   * already in-flight or completed, subsequent calls will await the same
+   * promise, preventing duplicate work and race conditions.
+   *
+   * On failure, the stored promise is cleared so callers may retry
+   * initialization later.
+   * @returns Promise that resolves once the wallet is fully initialized
+   * @throws Error wrapping the underlying failure cause from
+   * {@link performInitialization}
+   */
+  protected async initialize() {
+    if (this.initPromise) return this.initPromise
+    this.initPromise = (async () => {
+      try {
+        await this.performInitialization()
+      } catch (error) {
+        // Clear cached promise to allow retry after a failure
+        this.initPromise = undefined
+        throw new Error('Failed to initialize wallet', { cause: error })
+      }
+    })()
+    return this.initPromise
+  }
+
+  /**
+   * Send a transaction using this actions wallet
+   * @description Executes a transaction through the actions wallet.
+   * @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<TransactionReturnType>
+
+  /**
+   * Send a batch of transactions using this actions wallet
+   * @description Executes a batch of transactions through the actions wallet.
+   * @param transactionData - The transaction data to execute
+   * @param chainId - Target blockchain chain ID
+   * @returns Promise resolving to the transaction hash
+   */
+  abstract sendBatch(
+    transactionData: TransactionData[],
+    chainId: SupportedChainId,
+  ): Promise<BatchTransactionReturnType>
+}

package/src/wallet/core/wallets/abstract/__mocks__/TestWallet.ts

@@ -0,0 +1,40 @@
+import type { Address, LocalAccount, WalletClient } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { TransactionData } from '@/types/lend/index.js'
+import type { EOATransactionReceipt } from '@/wallet/core/wallets/abstract/types/index.js'
+import { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+
+export class TestWallet extends Wallet {
+  public readonly address: Address
+  public readonly signer: LocalAccount
+
+  constructor(
+    chainManager: ChainManager,
+    address: Address,
+    signer: LocalAccount,
+  ) {
+    super(chainManager)
+    this.address = address
+    this.signer = signer
+  }
+
+  async walletClient(_chainId: SupportedChainId): Promise<WalletClient> {
+    return {} as unknown as WalletClient
+  }
+
+  async send(
+    _transactionData: TransactionData,
+    _chainId: SupportedChainId,
+  ): Promise<EOATransactionReceipt> {
+    return {} as unknown as EOATransactionReceipt
+  }
+
+  async sendBatch(
+    _transactionData: TransactionData[],
+    _chainId: SupportedChainId,
+  ): Promise<EOATransactionReceipt[]> {
+    return [] as unknown as EOATransactionReceipt[]
+  }
+}

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

@@ -0,0 +1,61 @@
+import type { LocalAccount } from 'viem'
+import { unichain } from 'viem/chains'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { WalletLendNamespace } from '@/lend/namespaces/WalletLendNamespace.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import { fetchERC20Balance, fetchETHBalance } from '@/services/tokenBalance.js'
+import { SUPPORTED_TOKENS } from '@/supported/tokens.js'
+import { MockChainManager } from '@/test/MockChainManager.js'
+import { getRandomAddress } from '@/test/utils.js'
+import { TestWallet } from '@/wallet/core/wallets/abstract/__mocks__/TestWallet.js'
+
+vi.mock('@/services/tokenBalance.js', async () => {
+  return {
+    fetchETHBalance: vi.fn().mockResolvedValue({} as unknown),
+    fetchERC20Balance: vi.fn().mockResolvedValue({} as unknown),
+  }
+})
+
+describe('Wallet (base)', () => {
+  const chainManager = new MockChainManager({
+    supportedChains: [unichain.id],
+  }) as unknown as ChainManager
+
+  const address = getRandomAddress()
+  const signer = { address } as unknown as LocalAccount
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('getBalance fetches ETH and ERC20 balances for all supported tokens', async () => {
+    const wallet = new TestWallet(chainManager, address, signer)
+
+    const result = await wallet.getBalance()
+
+    expect(result).toBeTruthy()
+    expect(fetchETHBalance).toHaveBeenCalledTimes(1)
+    expect(fetchETHBalance).toHaveBeenCalledWith(chainManager, address)
+    // Should call fetchERC20Balance for each token in SUPPORTED_TOKENS
+    expect(fetchERC20Balance).toHaveBeenCalledTimes(
+      Object.keys(SUPPORTED_TOKENS).length,
+    )
+  })
+
+  it('getBalance propagates errors from underlying fetchers', async () => {
+    vi.mocked(fetchETHBalance).mockRejectedValueOnce(new Error('rpc error'))
+
+    const wallet = new TestWallet(chainManager, address, signer)
+
+    await expect(wallet.getBalance()).rejects.toThrow('rpc error')
+  })
+
+  it('has lend namespace available for inheritance', () => {
+    const wallet = new TestWallet(chainManager, address, signer)
+
+    wallet.lend = {} as WalletLendNamespace
+    expect(wallet.lend).toBeDefined()
+    expect(wallet.lend).toEqual({})
+  })
+})

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

@@ -0,0 +1,42 @@
+import type { TransactionReceipt } from 'viem'
+import type { WaitForUserOperationReceiptReturnType } from 'viem/account-abstraction'
+
+/**
+ * Transaction receipt for EOA (Externally Owned Account) transactions.
+ *
+ * Standard Ethereum transaction receipt from regular transactions sent by EOA wallets.
+ */
+export type EOATransactionReceipt = TransactionReceipt<
+  bigint,
+  number,
+  'success' | 'reverted'
+>
+
+/**
+ * Transaction receipt for ERC-4337 UserOperations.
+ *
+ * Receipt from smart wallet transactions processed through bundlers.
+ * Contains `userOpHash` to identify the UserOperation.
+ */
+export type UserOperationTransactionReceipt =
+  WaitForUserOperationReceiptReturnType
+
+/**
+ * Return type for single transaction operations.
+ *
+ * Can be either an EOA transaction receipt or a UserOperation receipt,
+ * depending on the wallet type used.
+ */
+export type TransactionReturnType =
+  | EOATransactionReceipt
+  | UserOperationTransactionReceipt
+
+/**
+ * Return type for batch transaction operations.
+ *
+ * EOA wallets return an array of receipts (one per transaction), while
+ * smart wallets return a single UserOperation receipt for the entire batch.
+ */
+export type BatchTransactionReturnType =
+  | EOATransactionReceipt[]
+  | UserOperationTransactionReceipt

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

@@ -0,0 +1,96 @@
+import type {
+  Chain,
+  FallbackTransport,
+  HttpTransport,
+  LocalAccount,
+  WalletClient,
+} from 'viem'
+import { createWalletClient } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { TransactionData } from '@/types/lend/index.js'
+import type { EOATransactionReceipt } from '@/wallet/core/wallets/abstract/types/index.js'
+import { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+
+/**
+ * Base class for Externally Owned Account (EOA) wallets.
+ *
+ * EOA wallets send standard Ethereum transactions signed by a private key,
+ * without using ERC-4337 account abstraction features (bundlers, UserOperations, paymasters).
+ * Transactions are submitted directly to the network and processed by validators.
+ */
+export abstract class EOAWallet extends Wallet {
+  /**
+   * Create a WalletClient for this EOA wallet.
+   *
+   * Creates a viem-compatible WalletClient configured with this wallet's account
+   * and the specified chain. Supports fallback transport for multiple RPC URLs.
+   * @param chainId - The chain ID to create the wallet client for
+   * @returns Promise resolving to a WalletClient configured for the specified chain
+   */
+  async walletClient(
+    chainId: SupportedChainId,
+  ): Promise<
+    WalletClient<
+      | HttpTransport<undefined, false>
+      | FallbackTransport<Array<HttpTransport<undefined, false>>>,
+      Chain,
+      LocalAccount,
+      []
+    >
+  > {
+    return createWalletClient({
+      account: this.signer,
+      chain: this.chainManager.getChain(chainId),
+      transport: this.chainManager.getTransportForChain(chainId),
+    })
+  }
+
+  /**
+   * Send a single transaction from this EOA wallet.
+   *
+   * Creates a wallet client, sends the transaction, and waits for the receipt.
+   * @param transactionData - Transaction to send (to, value, data, etc.)
+   * @param chainId - Chain to send the transaction on
+   * @returns Promise resolving to the transaction receipt
+   */
+  async send(
+    transactionData: TransactionData,
+    chainId: SupportedChainId,
+  ): Promise<EOATransactionReceipt> {
+    const walletClient = await this.walletClient(chainId)
+    const txHash = await walletClient.sendTransaction(transactionData)
+    const publicClient = this.chainManager.getPublicClient(chainId)
+    const receipt = await publicClient.waitForTransactionReceipt({
+      hash: txHash,
+    })
+    return receipt
+  }
+
+  /**
+   * Send multiple transactions sequentially from this EOA wallet.
+   *
+   * Executes transactions one at a time in order, waiting for 2 confirmations
+   * between each to ensure nonce updates. Returns an array of receipts.
+   * @param transactionData - Array of transactions to send
+   * @param chainId - Chain to send the transactions on
+   * @returns Promise resolving to array of transaction receipts (one per transaction)
+   */
+  async sendBatch(
+    transactionData: TransactionData[],
+    chainId: SupportedChainId,
+  ): Promise<EOATransactionReceipt[]> {
+    const receipts: EOATransactionReceipt[] = []
+    for (const tx of transactionData) {
+      const receipt = await this.send(tx, chainId)
+      const publicClient = this.chainManager.getPublicClient(chainId)
+      // wait an extra confirmation so give time for nonce to be updated
+      await publicClient.waitForTransactionReceipt({
+        hash: receipt.transactionHash,
+        confirmations: 2,
+      })
+      receipts.push(receipt)
+    }
+    return receipts
+  }
+}

package/src/wallet/core/wallets/eoa/__mocks__/EOAWallet.ts

@@ -0,0 +1,112 @@
+import type { Address, LocalAccount, WalletClient } from 'viem'
+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 { EOATransactionReceipt } from '@/wallet/core/wallets/abstract/types/index.js'
+import type { EOAWallet } from '@/wallet/core/wallets/eoa/EOAWallet.js'
+
+export type CreateEOAWalletMockOptions = {
+  /** Mock wallet address */
+  address?: Address
+  /** Mock signer */
+  signer?: LocalAccount
+  /** Custom implementation for walletClient */
+  walletClientImpl?: (chainId: SupportedChainId) => Promise<WalletClient>
+  /** Custom implementation for send */
+  sendImpl?: (
+    transactionData: TransactionData,
+    chainId: SupportedChainId,
+  ) => Promise<EOATransactionReceipt>
+  /** Custom implementation for sendBatch */
+  sendBatchImpl?: (
+    transactionData: TransactionData[],
+    chainId: SupportedChainId,
+  ) => Promise<EOATransactionReceipt[]>
+  /** Optional custom sendTokens implementation */
+  sendTokensImpl?: (
+    amount: number,
+    asset: Asset,
+    chainId: SupportedChainId,
+    recipientAddress: Address,
+  ) => Promise<TransactionData>
+}
+
+/**
+ * Create a mock EOAWallet instance
+ * @description Returns an object typed as `EOAWallet` with configurable
+ * implementations for `send`, `sendBatch`, and `walletClient`. Other abstract
+ * members are provided with minimal defaults or throw if invoked (unless overridden).
+ */
+export function createMock(
+  options: CreateEOAWalletMockOptions = {},
+): EOAWallet {
+  const defaultReceipt = {
+    transactionHash:
+      '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+    blockNumber: 12345n,
+    status: 'success',
+  } as unknown as EOATransactionReceipt
+
+  const address: Address = (options.address ??
+    '0x0000000000000000000000000000000000000000') as Address
+  const signer: LocalAccount =
+    options.signer ?? ({ address, type: 'local' } as unknown as LocalAccount)
+
+  const walletClient = vi.fn(
+    async (chainId: SupportedChainId): Promise<WalletClient> => {
+      if (options.walletClientImpl) return options.walletClientImpl(chainId)
+      throw new Error('walletClient not implemented in EOAWallet mock')
+    },
+  )
+
+  const send = vi.fn(
+    async (
+      transactionData: TransactionData,
+      chainId: SupportedChainId,
+    ): Promise<EOATransactionReceipt> => {
+      if (options.sendImpl) return options.sendImpl(transactionData, chainId)
+      return defaultReceipt
+    },
+  )
+
+  const sendBatch = vi.fn(
+    async (
+      transactionData: TransactionData[],
+      chainId: SupportedChainId,
+    ): Promise<EOATransactionReceipt[]> => {
+      if (options.sendBatchImpl)
+        return options.sendBatchImpl(transactionData, chainId)
+      return [defaultReceipt]
+    },
+  )
+
+  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 EOAWallet mock')
+    },
+  )
+
+  const mock = {
+    get address() {
+      return address
+    },
+    get signer() {
+      return signer
+    },
+    walletClient,
+    send,
+    sendBatch,
+    sendTokens,
+  } as unknown as EOAWallet
+
+  return mock
+}