@eth-optimism/actions-sdk 0.0.2

package/src/services/ChainManager.spec.ts

@@ -0,0 +1,332 @@
+import { chainById } from '@eth-optimism/viem/chains'
+import { createSmartAccountClient } from 'permissionless/clients'
+import { createPimlicoClient } from 'permissionless/clients/pimlico'
+import type {
+  FallbackTransport,
+  HttpTransport,
+  PublicClient,
+  Transport,
+} from 'viem'
+import { createPublicClient, fallback, http } from 'viem'
+import { createBundlerClient } 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 { ChainManager } from '@/services/ChainManager.js'
+import type { ChainConfig, PimlicoBundlerConfig } from '@/types/chain.js'
+
+vi.mock('viem', async () => ({
+  // @ts-ignore - importActual returns unknown
+  ...(await vi.importActual('viem')),
+  createPublicClient: vi.fn(),
+  fallback: vi.fn(),
+  http: vi.fn().mockImplementation((url) => url as unknown as HttpTransport),
+}))
+
+vi.mock('viem/account-abstraction', () => {
+  return {
+    createBundlerClient: vi
+      .fn()
+      .mockReturnValue({ __type: 'bundlerClient' } as unknown),
+  }
+})
+
+vi.mock('permissionless/clients/pimlico', () => {
+  return {
+    createPimlicoClient: vi.fn().mockReturnValue({
+      getUserOperationGasPrice: vi.fn().mockResolvedValue({
+        fast: { maxFeePerGas: 1n, maxPriorityFeePerGas: 1n },
+      }),
+    } as unknown),
+  }
+})
+
+vi.mock('permissionless/clients', () => {
+  return {
+    createSmartAccountClient: vi
+      .fn()
+      .mockReturnValue({ __type: 'smartAccountClient' } as unknown),
+  }
+})
+
+describe('ChainManager', () => {
+  let chainManager: ChainManager
+  let mockChainConfigs: ChainConfig[]
+  let mockFallbackTransport: FallbackTransport<readonly Transport[]>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(createPublicClient).mockImplementation(
+      ({ chain }) =>
+        ({
+          chain,
+        }) as unknown as PublicClient,
+    )
+    mockFallbackTransport = {
+      __type: 'fallback',
+    } as unknown as FallbackTransport<readonly Transport[]>
+    vi.mocked(fallback).mockReturnValue(mockFallbackTransport)
+    mockChainConfigs = [
+      {
+        chainId: unichain.id,
+        rpcUrls: ['https://rpc.unichain.org'],
+      },
+    ]
+    chainManager = new ChainManager(mockChainConfigs)
+  })
+
+  describe('constructor', () => {
+    it('should create ChainManager with chain configs', () => {
+      expect(chainManager).toBeInstanceOf(ChainManager)
+    })
+
+    it('should throw error for unknown chain ID', () => {
+      const invalidChainConfigs = [
+        {
+          chainId: 99999 as unknown as SupportedChainId,
+          rpcUrl: 'https://invalid.rpc',
+        },
+      ]
+
+      expect(() => new ChainManager(invalidChainConfigs)).toThrow(
+        'Chain not found for ID: 99999',
+      )
+    })
+
+    it('should throw error if multiple chains configured with the same chain ID', () => {
+      const multiChainConfigs: ChainConfig[] = [
+        { chainId: unichain.id, rpcUrls: ['https://sepolia.unichain.org'] },
+        { chainId: unichain.id, rpcUrls: ['https://another.rpc'] },
+      ]
+      expect(() => new ChainManager(multiChainConfigs)).toThrow(
+        `Public client already configured for chain ID: ${unichain.id}`,
+      )
+    })
+  })
+
+  describe('getPublicClient', () => {
+    it('should return public client for configured chain', () => {
+      const client = chainManager.getPublicClient(unichain.id)
+
+      expect(client).toBeDefined()
+      expect(client.chain!.id).toBe(unichain.id)
+    })
+
+    it('should throw error for unsupported chain', () => {
+      const unsupportedChainId = 999 as unknown as SupportedChainId
+
+      expect(() => chainManager.getPublicClient(unsupportedChainId)).toThrow(
+        'No public client configured for chain ID: 999',
+      )
+    })
+  })
+
+  describe('getSupportedChains', () => {
+    it('should return array of supported chain IDs', () => {
+      const supportedChains = chainManager.getSupportedChains()
+      expect(supportedChains).toEqual([unichain.id])
+    })
+  })
+
+  describe('getTransportForChain', () => {
+    it('should return fallback transport when multiple RPC URLs are configured', () => {
+      // clear mocks for fallback
+      vi.clearAllMocks()
+      const transport = chainManager.getTransportForChain(unichain.id)
+
+      expect(transport).toBeDefined()
+      expect(fallback).toHaveBeenCalledTimes(1)
+      expect(transport).toEqual(mockFallbackTransport)
+      expect(fallback).toHaveBeenCalledWith(['https://rpc.unichain.org'])
+    })
+
+    it('should return http transport when no RPC URLs are configured', () => {
+      const configWithoutRpcUrls: ChainConfig[] = [
+        {
+          chainId: unichain.id,
+        },
+      ]
+      const mgr = new ChainManager(configWithoutRpcUrls)
+      vi.clearAllMocks()
+      const mockHttpTransport = { __type: 'http' } as unknown as HttpTransport
+      vi.mocked(http).mockReturnValue(mockHttpTransport)
+
+      const transport = mgr.getTransportForChain(unichain.id)
+
+      expect(http).toHaveBeenCalledTimes(1)
+      expect(http).toHaveBeenCalledWith()
+      expect(transport).toEqual(mockHttpTransport)
+    })
+
+    it('should return http transport when empty RPC URLs array is configured', () => {
+      const configWithEmptyRpcUrls: ChainConfig[] = [
+        {
+          chainId: unichain.id,
+          rpcUrls: [],
+        },
+      ]
+      const mgr = new ChainManager(configWithEmptyRpcUrls)
+      vi.clearAllMocks()
+      const mockHttpTransport = { __type: 'http' } as unknown as HttpTransport
+      vi.mocked(http).mockReturnValue(mockHttpTransport)
+
+      const transport = mgr.getTransportForChain(unichain.id)
+
+      expect(http).toHaveBeenCalledTimes(1)
+      expect(http).toHaveBeenCalledWith()
+      expect(transport).toEqual(mockHttpTransport)
+    })
+
+    it('should throw error for unsupported chain', () => {
+      const unsupportedChainId = 999 as unknown as SupportedChainId
+
+      expect(() =>
+        chainManager.getTransportForChain(unsupportedChainId),
+      ).toThrow('No chain config found for chain ID: 999')
+    })
+  })
+
+  describe('getBundlerClient', () => {
+    const mockAccount = {
+      entryPoint: {
+        address: '0x0000000000000000000000000000000000000005',
+        version: '0.6',
+      },
+    } as unknown as Parameters<ChainManager['getBundlerClient']>[1]
+
+    it('returns Pimlico SmartAccountClient when bundler type is pimlico (with sponsorshipPolicyId)', async () => {
+      const bundlerConfig: PimlicoBundlerConfig = {
+        type: 'pimlico',
+        url: 'https://pimlico.example',
+        sponsorshipPolicyId: 'policy-123',
+      }
+      const configs: ChainConfig[] = [
+        {
+          chainId: unichain.id,
+          rpcUrls: ['https://rpc.unichain.org'],
+          bundler: bundlerConfig,
+        },
+      ]
+
+      const mgr = new ChainManager(configs)
+      const client = mgr.getBundlerClient(unichain.id, mockAccount)
+
+      expect(client).toEqual({ __type: 'smartAccountClient' })
+      expect(createPimlicoClient).toHaveBeenCalledTimes(1)
+      expect(createPimlicoClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          chain: chainById[unichain.id],
+          entryPoint: {
+            address: mockAccount.entryPoint.address,
+            version: mockAccount.entryPoint.version,
+          },
+        }),
+      )
+      expect(createSmartAccountClient).toHaveBeenCalledTimes(1)
+      expect(createSmartAccountClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          account: mockAccount,
+          chain: chainById[unichain.id],
+          paymasterContext: {
+            sponsorshipPolicyId: bundlerConfig.sponsorshipPolicyId!,
+          },
+          userOperation: {
+            estimateFeesPerGas: expect.any(Function),
+          },
+        }),
+      )
+    })
+
+    it('returns Pimlico SmartAccountClient when bundler type is pimlico (without sponsorshipPolicyId)', async () => {
+      const configs: ChainConfig[] = [
+        {
+          chainId: unichain.id,
+          rpcUrls: ['https://rpc.unichain.org'],
+          bundler: {
+            type: 'pimlico',
+            url: 'https://pimlico.example',
+          },
+        },
+      ]
+
+      const mgr = new ChainManager(configs)
+
+      const client = mgr.getBundlerClient(unichain.id, mockAccount)
+      expect(client).toEqual({ __type: 'smartAccountClient' })
+      expect(createPimlicoClient).toHaveBeenCalledTimes(1)
+      expect(createSmartAccountClient).toHaveBeenCalledTimes(1)
+      expect(createSmartAccountClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          account: mockAccount,
+          chain: chainById[unichain.id],
+          paymasterContext: undefined,
+          userOperation: {
+            estimateFeesPerGas: expect.any(Function),
+          },
+        }),
+      )
+    })
+
+    it('returns viem BundlerClient when bundler type is simple', async () => {
+      const configs: ChainConfig[] = [
+        {
+          chainId: unichain.id,
+          rpcUrls: ['https://rpc.unichain.org'],
+          bundler: {
+            type: 'simple',
+            url: 'https://bundler.example',
+          },
+        },
+      ]
+
+      const mgr = new ChainManager(configs)
+
+      const client = mgr.getBundlerClient(unichain.id, mockAccount)
+      expect(client).toEqual({ __type: 'bundlerClient' })
+      expect(createBundlerClient).toHaveBeenCalledTimes(1)
+      expect(createBundlerClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          account: mockAccount,
+          chain: chainById[unichain.id],
+        }),
+      )
+      expect(createPimlicoClient).not.toHaveBeenCalled()
+      expect(createSmartAccountClient).not.toHaveBeenCalled()
+    })
+
+    it('throws when no bundler is configured for the chain', () => {
+      const configs: ChainConfig[] = [
+        {
+          chainId: unichain.id,
+          rpcUrls: ['https://rpc.unichain.org'],
+        },
+      ]
+
+      const mgr = new ChainManager(configs)
+
+      expect(() => mgr.getBundlerClient(unichain.id, mockAccount)).toThrow(
+        `No bundler configured for chain ID: ${unichain.id}`,
+      )
+    })
+
+    it('throws when bundler URL is empty for simple bundler', () => {
+      const configs: ChainConfig[] = [
+        {
+          chainId: unichain.id,
+          rpcUrls: ['https://rpc.unichain.org'],
+          bundler: {
+            type: 'simple',
+            url: '',
+          },
+        },
+      ]
+
+      const mgr = new ChainManager(configs)
+
+      expect(() => mgr.getBundlerClient(unichain.id, mockAccount)).toThrow(
+        `No bundler URL configured for chain ID: ${unichain.id}`,
+      )
+    })
+  })
+})

package/src/services/ChainManager.ts

@@ -0,0 +1,237 @@
+import { chainById } from '@eth-optimism/viem/chains'
+import type { SmartAccountClient } from 'permissionless/clients'
+import { createSmartAccountClient } from 'permissionless/clients'
+import { createPimlicoClient } from 'permissionless/clients/pimlico'
+import {
+  type Chain,
+  createPublicClient,
+  fallback,
+  http,
+  type PublicClient,
+} from 'viem'
+import type { BundlerClient, SmartAccount } from 'viem/account-abstraction'
+import { createBundlerClient } from 'viem/account-abstraction'
+
+import type { SUPPORTED_CHAIN_IDS } from '@/constants/supportedChains.js'
+import type { ChainConfig } from '@/types/chain.js'
+
+/**
+ * Chain Manager Service
+ * @description Manages public clients and chain infrastructure for the Verbs SDK.
+ * Provides utilities for accessing RPC and bundler URLs, and creating clients for supported chains.
+ */
+export class ChainManager {
+  /** Map of chain IDs to their corresponding public clients */
+  private publicClients: Map<(typeof SUPPORTED_CHAIN_IDS)[number], PublicClient>
+  /** Configuration for each supported chain */
+  private chainConfigs: ChainConfig[]
+
+  /**
+   * Initialize the ChainManager with chain configurations
+   * @param chains - Array of chain configurations
+   */
+  constructor(chains: ChainConfig[]) {
+    this.chainConfigs = chains
+    this.publicClients = this.createPublicClients(chains)
+  }
+
+  /**
+   * Get public client for a specific chain
+   * @param chainId - The chain ID to retrieve the public client for
+   * @returns PublicClient instance for the specified chain
+   * @throws Error if no client is configured for the chain ID
+   */
+  getPublicClient(chainId: (typeof SUPPORTED_CHAIN_IDS)[number]): PublicClient {
+    const client = this.publicClients.get(chainId)
+    if (!client) {
+      throw new Error(`No public client configured for chain ID: ${chainId}`)
+    }
+    return client
+  }
+
+  /**
+   * Get bundler client for a specific chain
+   * @param chainId - The chain ID to retrieve the bundler client for
+   * @param account - SmartAccount to use with the bundler client
+   * @returns BundlerClient instance for the specified chain
+   * @throws Error if no bundler URL is configured for the chain ID
+   */
+  getBundlerClient(
+    chainId: (typeof SUPPORTED_CHAIN_IDS)[number],
+    account: SmartAccount,
+  ): BundlerClient | SmartAccountClient {
+    const chainConfig = this.getChainConfig(chainId)
+    const bundlerConfig = chainConfig.bundler
+    if (!bundlerConfig) {
+      throw new Error(`No bundler configured for chain ID: ${chainId}`)
+    }
+    if (bundlerConfig.type === 'pimlico') {
+      return this.getPimlicoBundlerClient(
+        chainId,
+        account,
+        bundlerConfig.sponsorshipPolicyId,
+      )
+    }
+    const bundlerUrl = this.getBundlerUrl(chainId)
+    if (!bundlerUrl) {
+      throw new Error(`No bundler URL configured for chain ID: ${chainId}`)
+    }
+    const client = createPublicClient({
+      chain: this.getChain(chainId),
+      transport: http(bundlerUrl),
+    })
+    return createBundlerClient({
+      account,
+      client,
+      transport: http(bundlerUrl),
+      chain: this.getChain(chainId),
+    })
+  }
+
+  /**
+   * Get RPC URL for a specific chain
+   * @param chainId - The chain ID to retrieve the RPC URL for
+   * @returns RPC URL as a string
+   * @throws Error if no chain config is found for the chain ID
+   */
+  getRpcUrls(
+    chainId: (typeof SUPPORTED_CHAIN_IDS)[number],
+  ): string[] | undefined {
+    const chainConfig = this.getChainConfig(chainId)
+    return chainConfig.rpcUrls
+  }
+
+  /**
+   * Get bundler URL for a specific chain
+   * @param chainId - The chain ID to retrieve the bundler URL for
+   * @returns Bundler URL as a string or undefined if not configured
+   * @throws Error if no chain config is found for the chain ID
+   */
+  getBundlerUrl(
+    chainId: (typeof SUPPORTED_CHAIN_IDS)[number],
+  ): string | undefined {
+    const chainConfig = this.getChainConfig(chainId)
+    if (!chainConfig.bundler) {
+      throw new Error(`No bundler configured for chain ID: ${chainId}`)
+    }
+    return chainConfig.bundler.url
+  }
+
+  /**
+   * Get chain information for a specific chain ID
+   * @param chainId - The chain ID to retrieve information for
+   * @returns Chain object containing chain details
+   */
+  getChain(chainId: (typeof SUPPORTED_CHAIN_IDS)[number]): Chain {
+    return chainById[chainId]
+  }
+
+  /**
+   * Get all supported chain IDs
+   * @returns Array of supported chain IDs
+   */
+  getSupportedChains() {
+    return this.chainConfigs.map((c) => c.chainId)
+  }
+
+  /**
+   * Get transport for a specific chain with fallback support
+   * @param chainId - The chain ID to retrieve the transport for
+   * @returns Transport configured with fallback RPC URLs or default http transport
+   * @throws Error if no chain config is found for the chain ID
+   */
+  getTransportForChain(chainId: (typeof SUPPORTED_CHAIN_IDS)[number]) {
+    const rpcUrls = this.getRpcUrls(chainId)
+    return rpcUrls?.length
+      ? fallback(rpcUrls.map((rpcUrl) => http(rpcUrl)))
+      : http()
+  }
+
+  /**
+   * Create public clients for all configured chains
+   * @param chains - Array of chain configurations
+   * @returns Map of chain IDs to their corresponding public clients
+   * @throws Error if a chain is not found or already configured
+   */
+  private createPublicClients(
+    chains: ChainConfig[],
+  ): Map<(typeof SUPPORTED_CHAIN_IDS)[number], PublicClient> {
+    const clients = new Map<
+      (typeof SUPPORTED_CHAIN_IDS)[number],
+      PublicClient
+    >()
+
+    for (const chainConfig of chains) {
+      const chain = chainById[chainConfig.chainId]
+      if (!chain) {
+        throw new Error(`Chain not found for ID: ${chainConfig.chainId}`)
+      }
+      if (clients.has(chainConfig.chainId)) {
+        throw new Error(
+          `Public client already configured for chain ID: ${chainConfig.chainId}`,
+        )
+      }
+      const client = createPublicClient({
+        chain,
+        transport: this.getTransportForChain(chainConfig.chainId),
+      })
+
+      clients.set(chainConfig.chainId, client)
+    }
+
+    return clients
+  }
+
+  /**
+   * Get chain config for a specific chain ID
+   * @param chainId The chain ID to retrieve the chain config for
+   * @returns ChainConfig object containing chain details
+   */
+  private getChainConfig(
+    chainId: (typeof SUPPORTED_CHAIN_IDS)[number],
+  ): ChainConfig {
+    const chainConfig = this.chainConfigs.find((c) => c.chainId === chainId)
+    if (!chainConfig) {
+      throw new Error(`No chain config found for chain ID: ${chainId}`)
+    }
+    return chainConfig
+  }
+
+  /**
+   * Get Pimlico bundler client for a specific chain
+   * @param chainId - The chain ID to retrieve the Pimlico bundler client for
+   * @param account - SmartAccount to use with the Pimlico bundler client
+   * @param sponsorshipPolicyId - The sponsorship policy ID to use with the Pimlico bundler client
+   * @returns Pimlico bundler client for the specified chain
+   */
+  private getPimlicoBundlerClient(
+    chainId: (typeof SUPPORTED_CHAIN_IDS)[number],
+    account: SmartAccount,
+    sponsorshipPolicyId?: string,
+  ) {
+    const bundlerUrl = this.getBundlerUrl(chainId)
+    const pimlicoClient = createPimlicoClient({
+      chain: this.getChain(chainId),
+      transport: http(bundlerUrl),
+      entryPoint: {
+        address: account.entryPoint.address,
+        version: account.entryPoint.version,
+      },
+    })
+    const smartClient = createSmartAccountClient({
+      account,
+      chain: this.getChain(chainId),
+      bundlerTransport: http(bundlerUrl),
+      paymasterContext: sponsorshipPolicyId
+        ? {
+            sponsorshipPolicyId,
+          }
+        : undefined,
+      userOperation: {
+        estimateFeesPerGas: async () =>
+          (await pimlicoClient.getUserOperationGasPrice()).fast,
+      },
+    })
+    return smartClient
+  }
+}

package/src/services/tokenBalance.spec.ts

@@ -0,0 +1,93 @@
+import type { Address } from 'viem'
+import { unichain } from 'viem/chains'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { ETH } from '@/constants/assets.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import { fetchERC20Balance, fetchETHBalance } from '@/services/tokenBalance.js'
+import { MockUSDCAsset } from '@/test/MockAssets.js'
+import { MockChainManager } from '@/test/MockChainManager.js'
+import type { Asset } from '@/types/asset.js'
+
+describe('TokenBalance', () => {
+  let chainManager: ChainManager
+  const walletAddress: Address = '0x1234567890123456789012345678901234567890'
+
+  beforeEach(() => {
+    chainManager = new MockChainManager({
+      supportedChains: [unichain.id],
+      defaultBalance: 1000000n,
+    }) as any
+  })
+
+  describe('fetchBalance', () => {
+    it('should fetch token balance across supported chains', async () => {
+      const balance = await fetchERC20Balance(
+        chainManager,
+        walletAddress,
+        MockUSDCAsset,
+      )
+
+      expect(balance).toEqual({
+        symbol: 'USDC',
+        totalBalance: 1000000n,
+        totalFormattedBalance: '1',
+        chainBalances: [
+          {
+            chainId: unichain.id,
+            balance: 1000000n,
+            formattedBalance: '1',
+            tokenAddress: MockUSDCAsset.address[unichain.id]!,
+          },
+        ],
+      })
+    })
+
+    it('should return zero balance when token not supported on any chains', async () => {
+      const unsupportedAsset: Asset = {
+        metadata: {
+          symbol: 'UNSUPPORTED',
+          name: 'Unsupported Token',
+          decimals: 18,
+        },
+        address: {
+          27637: '0xBAa5CC21fd487B8Fcc2F632f3F4E8D37262a0842',
+        } as any,
+        type: 'erc20',
+      }
+
+      const balance = await fetchERC20Balance(
+        chainManager,
+        walletAddress,
+        unsupportedAsset,
+      )
+
+      expect(balance).toEqual({
+        symbol: 'UNSUPPORTED',
+        totalBalance: 0n,
+        totalFormattedBalance: '0',
+        chainBalances: [],
+      })
+    })
+  })
+
+  describe('fetchETHBalance', () => {
+    it('should fetch ETH balance across supported chains', async () => {
+      const balance = await fetchETHBalance(chainManager, walletAddress)
+
+      expect(balance).toEqual({
+        symbol: 'ETH',
+        totalBalance: 1000000n,
+        totalFormattedBalance: '0.000000000001',
+        chainBalances: [
+          {
+            chainId: unichain.id,
+            balance: 1000000n,
+            formattedBalance: '0.000000000001',
+            tokenAddress: ETH.address[unichain.id]!,
+          },
+        ],
+      })
+    })
+  })
+})