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

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

@@ -0,0 +1,17 @@
+import type { WaitForUserOperationReceiptReturnType } from 'viem/account-abstraction'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { SmartWallet } from '@/wallet/core/wallets/smart/abstract/SmartWallet.js'
+import type { SmartWalletDeploymentError } from '@/wallet/core/wallets/smart/error/errors.js'
+
+interface SmartWalletDeployment {
+  chainId: SupportedChainId
+  success: boolean
+  receipt?: WaitForUserOperationReceiptReturnType
+  error?: SmartWalletDeploymentError
+}
+
+export type SmartWalletCreationResult<TWallet extends SmartWallet> = {
+  wallet: TWallet
+  deployments: SmartWalletDeployment[]
+}

package/src/wallet/core/providers/smart/default/DefaultSmartWalletProvider.ts

@@ -0,0 +1,175 @@
+import type { Address, Hex, LocalAccount } from 'viem'
+import { keccak256, slice, toHex } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import type { LendConfig, LendProvider } from '@/types/lend/index.js'
+import { SmartWalletProvider } from '@/wallet/core/providers/smart/abstract/SmartWalletProvider.js'
+import type { SmartWalletCreationResult } from '@/wallet/core/providers/smart/abstract/types/index.js'
+import type { Signer } from '@/wallet/core/wallets/smart/abstract/types/index.js'
+import {
+  smartWalletFactoryAbi,
+  smartWalletFactoryAddress,
+} from '@/wallet/core/wallets/smart/default/constants/index.js'
+import { DefaultSmartWallet } from '@/wallet/core/wallets/smart/default/DefaultSmartWallet.js'
+import { formatPublicKey } from '@/wallet/core/wallets/smart/default/utils/formatPublicKey.js'
+import { getSignerPublicKey } from '@/wallet/core/wallets/smart/default/utils/getSignerPublicKey.js'
+import { SmartWalletDeploymentError } from '@/wallet/core/wallets/smart/error/errors.js'
+
+/**
+ * Smart Wallet Provider
+ * @description Factory for creating and managing Smart Wallet instances.
+ * Handles wallet address prediction, creation, and retrieval using ERC-4337 account abstraction.
+ */
+export class DefaultSmartWalletProvider extends SmartWalletProvider {
+  /** Manages supported blockchain networks */
+  private chainManager: ChainManager
+  /** Provider for lending market operations */
+  private lendProvider?: LendProvider<LendConfig>
+  /** Optional 16-byte attribution suffix appended to callData */
+  private attributionSuffix?: Hex
+
+  /**
+   * Initialize the Smart Wallet Provider
+   * @param chainManager - Manages supported blockchain networks
+   * @param paymasterAndBundlerUrl - URL for ERC-4337 bundler and paymaster services
+   * @param lendProvider - Provider for lending market operations
+   */
+  constructor(
+    chainManager: ChainManager,
+    lendProvider?: LendProvider<LendConfig>,
+    attributionSuffix?: string,
+  ) {
+    super()
+    this.chainManager = chainManager
+    this.lendProvider = lendProvider
+    if (attributionSuffix) {
+      this.attributionSuffix =
+        DefaultSmartWalletProvider.computeAttributionSuffix(attributionSuffix)
+    }
+  }
+
+  static computeAttributionSuffix(attributionSuffix: string) {
+    return slice(keccak256(toHex(attributionSuffix)), 0, 16)
+  }
+
+  /**
+   * Create a new smart wallet instance
+   * @description Creates a new smart wallet and attempts to deploy it across all supported chains.
+   * The wallet address is deterministically calculated from owners and nonce. Deployment failures
+   * on individual chains do not prevent wallet creation - they are reported in the result.
+   * @param owners - Array of wallet owners (addresses or WebAuthn public keys)
+   * @param signer - Local account used for signing transactions
+   * @param nonce - Optional nonce for address generation (defaults to 0)
+   * @param deploymentChainIds - Optional chain IDs to deploy the wallet to.
+   * If not provided, the wallet will be deployed to all supported chains. If you would
+   * like to lazily deploy the wallet on first transaction, you can provide an empty array.
+   * @returns Promise resolving to deployment result containing:
+   * - `wallet`: The created SmartWallet instance
+   * - `deployments`: Array of deployment results with chainId, receipt, success flag, and error
+   */
+  async createWallet(params: {
+    signer: LocalAccount
+    signers?: Signer[]
+    nonce?: bigint
+    deploymentChainIds?: SupportedChainId[]
+  }): Promise<SmartWalletCreationResult<DefaultSmartWallet>> {
+    const { signers, signer, nonce, deploymentChainIds } = params
+    const wallet = await DefaultSmartWallet.create({
+      signers,
+      signer,
+      chainManager: this.chainManager,
+      lendProvider: this.lendProvider,
+      nonce,
+      attributionSuffix: this.attributionSuffix,
+    })
+
+    const deploymentResults = await Promise.allSettled(
+      (deploymentChainIds ?? this.chainManager.getSupportedChains()).map(
+        (chainId) => wallet.deploy(chainId),
+      ),
+    )
+    const deploymentSuccesses = deploymentResults
+      .filter(
+        (
+          r,
+        ): r is PromiseFulfilledResult<
+          Awaited<ReturnType<typeof wallet.deploy>>
+        > => r.status === 'fulfilled',
+      )
+      .map((r) => {
+        return {
+          chainId: r.value.chainId,
+          receipt: r.value.receipt,
+          success: r.value.success,
+        }
+      })
+
+    const deploymentFailures = deploymentResults
+      .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
+      .map((r) => {
+        if (r.reason instanceof SmartWalletDeploymentError) {
+          return { error: r.reason, chainId: r.reason.chainId, success: false }
+        }
+        throw new Error(`Unknown error: ${r.reason}`)
+      })
+
+    return {
+      wallet,
+      deployments: [...deploymentSuccesses, ...deploymentFailures],
+    }
+  }
+
+  /**
+   * Get the predicted smart wallet address
+   * @description Calculates the deterministic address where a smart wallet would be deployed
+   * given the specified owners and nonce. Uses CREATE2 for address prediction.
+   * @param params.owners - Array of wallet owners (addresses or WebAuthn public keys)
+   * @param params.nonce - Nonce for address generation (defaults to 0)
+   * @returns Promise resolving to the predicted wallet address
+   */
+  async getWalletAddress(params: { signers: Signer[]; nonce?: bigint }) {
+    const { signers, nonce = 0n } = params
+    const signerBytes = signers.map((signer) => {
+      const publicKey = getSignerPublicKey(signer)
+      return formatPublicKey(publicKey)
+    })
+
+    // Factory is the same accross all chains, so we can use the first chain to get the wallet address
+    const publicClient = this.chainManager.getPublicClient(
+      this.chainManager.getSupportedChains()[0],
+    )
+    const smartWalletAddress = await publicClient.readContract({
+      abi: smartWalletFactoryAbi,
+      address: smartWalletFactoryAddress,
+      functionName: 'getAddress',
+      args: [signerBytes, nonce],
+    })
+    return smartWalletAddress
+  }
+
+  /**
+   * Get an existing smart wallet instance
+   * @description Creates a SmartWallet instance for an already deployed wallet.
+   * Use this when you know the wallet address and want to interact with it.
+   * @param params.walletAddress - Address of the deployed smart wallet
+   * @param params.signer - Local account used for signing transactions
+   * @param params.ownerIndex - Index of the signer in the wallet's owner list (defaults to 0)
+   * @returns SmartWallet instance
+   */
+  async getWallet(params: {
+    walletAddress: Address
+    signer: LocalAccount
+    signers?: Signer[]
+  }): Promise<DefaultSmartWallet> {
+    const { walletAddress, signer, signers } = params
+    return DefaultSmartWallet.create({
+      signers,
+      signer,
+      chainManager: this.chainManager,
+      lendProvider: this.lendProvider,
+      deploymentAddress: walletAddress,
+      attributionSuffix: this.attributionSuffix,
+    })
+  }
+}

package/src/wallet/core/providers/smart/default/__tests__/DefaultSmartWalletProvider.spec.ts

@@ -0,0 +1,467 @@
+import {
+  type Address,
+  isHex,
+  keccak256,
+  type LocalAccount,
+  pad,
+  size,
+  slice,
+  toHex,
+} from 'viem'
+import type {
+  WaitForUserOperationReceiptReturnType,
+  WebAuthnAccount,
+} from 'viem/account-abstraction'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { ChainManager } from '@/services/ChainManager.js'
+import { MockChainManager } from '@/test/MockChainManager.js'
+import { createMockLendProvider } from '@/test/MockLendProvider.js'
+import { getRandomAddress } from '@/test/utils.js'
+import { DefaultSmartWalletProvider } from '@/wallet/core/providers/smart/default/DefaultSmartWalletProvider.js'
+import { createMock as createDefaultSmartWalletMock } from '@/wallet/core/wallets/smart/default/__mocks__/DefaultSmartWallet.js'
+import {
+  smartWalletFactoryAbi,
+  smartWalletFactoryAddress,
+} from '@/wallet/core/wallets/smart/default/constants/index.js'
+import { DefaultSmartWallet } from '@/wallet/core/wallets/smart/default/DefaultSmartWallet.js'
+
+const mockChainManager = new MockChainManager({
+  supportedChains: [1, 130],
+}) as unknown as ChainManager
+const mockLendProvider = createMockLendProvider()
+const mockSigner: LocalAccount = {
+  address: getRandomAddress(),
+  type: 'local',
+} as unknown as LocalAccount
+
+describe('DefaultSmartWalletProvider', () => {
+  const mockWallet: ReturnType<typeof createDefaultSmartWalletMock> =
+    createDefaultSmartWalletMock({
+      address: getRandomAddress(),
+      signer: mockSigner,
+    })
+  const createWalletSpy = vi
+    .spyOn(DefaultSmartWallet, 'create')
+    .mockResolvedValue(mockWallet as unknown as DefaultSmartWallet)
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('computeAttributionSuffix', () => {
+    it('returns first 16 bytes of keccak256(input)', () => {
+      const input = 'attribution-seed'
+      const expected = slice(keccak256(toHex(input)), 0, 16)
+
+      const actual = DefaultSmartWalletProvider.computeAttributionSuffix(input)
+
+      expect(actual).toBe(expected)
+      expect(isHex(actual)).toBe(true)
+      expect(size(actual)).toBe(16)
+    })
+
+    it('always returns a 16-byte suffix for arbitrarily long input', () => {
+      const input = 'x'.repeat(10_000)
+      const expected = slice(keccak256(toHex(input)), 0, 16)
+
+      const actual = DefaultSmartWalletProvider.computeAttributionSuffix(input)
+
+      expect(actual).toBe(expected)
+      expect(isHex(actual)).toBe(true)
+      expect(size(actual)).toBe(16)
+    })
+  })
+
+  it('should create a wallet and return deployment results', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const signers = [mockSigner.address, getRandomAddress()]
+    const nonce = BigInt(123)
+
+    // Mock deploy to succeed for all chains
+    vi.mocked(mockWallet.deploy).mockResolvedValueOnce({
+      chainId: 1,
+      success: true,
+      receipt: undefined,
+    })
+    vi.mocked(mockWallet.deploy).mockResolvedValueOnce({
+      chainId: 130,
+      success: true,
+      receipt: undefined,
+    })
+
+    const result = await provider.createWallet({
+      signers,
+      signer: mockSigner,
+      nonce,
+    })
+
+    expect(result.wallet).toBe(mockWallet)
+    expect(result.wallet.signer).toBe(mockSigner)
+    expect(result).toEqual({
+      wallet: mockWallet,
+      deployments: [
+        { chainId: 1, receipt: undefined, success: true },
+        { chainId: 130, receipt: undefined, success: true },
+      ],
+    })
+
+    // Verify deploy was called for each supported chain
+    expect(mockWallet.deploy).toHaveBeenCalledTimes(2)
+    expect(mockWallet.deploy).toHaveBeenCalledWith(1)
+    expect(mockWallet.deploy).toHaveBeenCalledWith(130)
+  })
+
+  it('should report deployment successes across multiple chains', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const signers = [mockSigner.address, getRandomAddress()]
+    const nonce = BigInt(123)
+
+    const mockReceipt = {
+      txHash: '0x123',
+      success: true,
+    } as unknown as WaitForUserOperationReceiptReturnType
+    // Mock deploy to succeed for different chains
+    vi.mocked(mockWallet.deploy)
+      .mockResolvedValueOnce({
+        chainId: 1,
+        success: true,
+        receipt: mockReceipt,
+      })
+      .mockResolvedValueOnce({
+        chainId: 130,
+        success: true,
+        receipt: undefined,
+      })
+
+    const result = await provider.createWallet({
+      signers,
+      signer: mockSigner,
+      nonce,
+    })
+
+    expect(result.deployments).toEqual([
+      { chainId: 1, receipt: mockReceipt, success: true },
+      { chainId: 130, receipt: undefined, success: true },
+    ])
+
+    // Verify deploy was called once per chain
+    expect(mockWallet.deploy).toHaveBeenCalledTimes(2)
+    expect(mockWallet.deploy).toHaveBeenCalledWith(1)
+    expect(mockWallet.deploy).toHaveBeenCalledWith(130)
+  })
+
+  it('should report deployment failures', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const signers = [mockSigner.address, getRandomAddress()]
+    const nonce = BigInt(123)
+
+    // Mock deploy to fail for all chains
+    const { SmartWalletDeploymentError } = await import(
+      '@/wallet/core/wallets/smart/error/errors.js'
+    )
+    vi.mocked(mockWallet.deploy)
+      .mockRejectedValueOnce(
+        new SmartWalletDeploymentError('Deployment failed', 1),
+      )
+      .mockRejectedValueOnce(
+        new SmartWalletDeploymentError('Deployment failed', 130),
+      )
+
+    const result = await provider.createWallet({
+      signers,
+      signer: mockSigner,
+      nonce,
+    })
+
+    expect(result).toEqual({
+      wallet: mockWallet,
+      deployments: [
+        {
+          chainId: 1,
+          error: new SmartWalletDeploymentError('Deployment failed', 1),
+          success: false,
+        },
+        {
+          chainId: 130,
+          error: new SmartWalletDeploymentError('Deployment failed', 130),
+          success: false,
+        },
+      ],
+    })
+
+    // Verify deploy was called for each chain
+    expect(mockWallet.deploy).toHaveBeenCalledTimes(2)
+  })
+
+  it('should handle mixed deployment successes and failures', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const signers = [mockSigner.address, getRandomAddress()]
+    const nonce = BigInt(123)
+
+    const { SmartWalletDeploymentError } = await import(
+      '@/wallet/core/wallets/smart/error/errors.js'
+    )
+
+    // Mock deploy to succeed for chain 1, fail for chain 130
+    vi.mocked(mockWallet.deploy)
+      .mockResolvedValueOnce({
+        chainId: 1,
+        success: true,
+        receipt: undefined,
+      })
+      .mockRejectedValueOnce(
+        new SmartWalletDeploymentError('Deployment failed on chain 130', 130),
+      )
+
+    const result = await provider.createWallet({
+      signers,
+      signer: mockSigner,
+      nonce,
+    })
+
+    expect(result).toEqual({
+      wallet: mockWallet,
+      deployments: [
+        { chainId: 1, receipt: undefined, success: true },
+        {
+          chainId: 130,
+          error: new SmartWalletDeploymentError(
+            'Deployment failed on chain 130',
+            130,
+          ),
+          success: false,
+        },
+      ],
+    })
+
+    // Verify deploy was called for both chains
+    expect(mockWallet.deploy).toHaveBeenCalledTimes(2)
+    expect(mockWallet.deploy).toHaveBeenCalledWith(1)
+    expect(mockWallet.deploy).toHaveBeenCalledWith(130)
+  })
+
+  it('should respect deploymentChainIds parameter', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const signers = [mockSigner.address, getRandomAddress()]
+    const nonce = BigInt(123)
+    const deploymentChainIds: SupportedChainId[] = [1]
+
+    vi.mocked(mockWallet.deploy).mockResolvedValue({
+      chainId: 1,
+      success: true,
+      receipt: undefined,
+    })
+
+    const result = await provider.createWallet({
+      signers,
+      signer: mockSigner,
+      nonce,
+      deploymentChainIds,
+    })
+
+    // Should only call deploy once for chain 1
+    expect(mockWallet.deploy).toHaveBeenCalledTimes(1)
+    expect(mockWallet.deploy).toHaveBeenCalledWith(1)
+    expect(result).toEqual({
+      wallet: mockWallet,
+      deployments: [{ chainId: 1, receipt: undefined, success: true }],
+    })
+  })
+
+  it('should throw error for non-SmartWalletDeploymentError failures', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const signers = [mockSigner.address, getRandomAddress()]
+    const nonce = BigInt(123)
+
+    // Mock deploy to throw a generic error (not SmartWalletDeploymentError)
+    vi.mocked(mockWallet.deploy).mockRejectedValue(new Error('Generic error'))
+
+    await expect(
+      provider.createWallet({
+        signers,
+        signer: mockSigner,
+        nonce,
+      }),
+    ).rejects.toThrow('Unknown error')
+  })
+
+  it('should get wallet address with correct contract call', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const signers = [mockSigner.address, getRandomAddress()]
+    const nonce = BigInt(456)
+    const mockAddress = getRandomAddress()
+
+    const publicClient = vi.mocked(mockChainManager.getPublicClient(1))
+    publicClient.readContract = vi.fn().mockResolvedValue(mockAddress)
+
+    const address = await provider.getWalletAddress({ signers, nonce })
+
+    expect(address).toBe(mockAddress)
+    expect(publicClient.readContract).toHaveBeenCalledWith({
+      abi: smartWalletFactoryAbi,
+      address: smartWalletFactoryAddress,
+      functionName: 'getAddress',
+      args: [signers.map((signer) => pad(signer)), nonce],
+    })
+  })
+
+  it('should get wallet address with default nonce', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const signers = [getRandomAddress()]
+    const mockAddress = getRandomAddress()
+
+    const publicClient = vi.mocked(mockChainManager.getPublicClient(1))
+    publicClient.readContract = vi.fn().mockResolvedValue(mockAddress)
+
+    const address = await provider.getWalletAddress({ signers })
+
+    expect(address).toBe(mockAddress)
+    expect(publicClient.readContract).toHaveBeenCalledWith({
+      abi: smartWalletFactoryAbi,
+      address: smartWalletFactoryAddress,
+      functionName: 'getAddress',
+      args: [signers.map((signer) => pad(signer)), BigInt(0)],
+    })
+  })
+
+  it('should handle WebAuthn accounts in wallet address calculation', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const webAuthnAccount: WebAuthnAccount = {
+      type: 'webAuthn',
+      publicKey: '0x123456789abcdef',
+    } as unknown as WebAuthnAccount
+    const signers = [getRandomAddress(), webAuthnAccount]
+    const mockAddress = getRandomAddress()
+
+    const publicClient = vi.mocked(mockChainManager.getPublicClient(1))
+    publicClient.readContract = vi.fn().mockResolvedValue(mockAddress)
+
+    const address = await provider.getWalletAddress({ signers })
+
+    expect(address).toBe(mockAddress)
+    expect(publicClient.readContract).toHaveBeenCalledWith({
+      abi: smartWalletFactoryAbi,
+      address: smartWalletFactoryAddress,
+      functionName: 'getAddress',
+      args: [
+        [pad(signers[0] as Address), webAuthnAccount.publicKey],
+        BigInt(0),
+      ],
+    })
+  })
+
+  it('should throw error for invalid signer type', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const invalidSigner = { type: 'invalid' } as unknown as Address
+    const signers = [invalidSigner]
+
+    await expect(provider.getWalletAddress({ signers })).rejects.toThrow(
+      'invalid signer type',
+    )
+  })
+
+  it('should get existing wallet', async () => {
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+    )
+    const walletAddress = getRandomAddress()
+
+    const wallet = await provider.getWallet({
+      walletAddress,
+      signer: mockSigner,
+      signers: [mockSigner.address],
+    })
+
+    // Verify DefaultSmartWallet.create was called with correct params
+    expect(createWalletSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        signers: [mockSigner.address],
+        signer: mockSigner,
+        deploymentAddress: walletAddress,
+      }),
+    )
+    expect(wallet).toBe(mockWallet)
+    expect(wallet.signer).toBe(mockSigner)
+    expect(wallet.address).toBeDefined()
+  })
+
+  it('passes attributionSuffix from constructor into createWallet', async () => {
+    const attributionSeed = 'https://my.app'
+    const expectedSuffix =
+      DefaultSmartWalletProvider.computeAttributionSuffix(attributionSeed)
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+      attributionSeed,
+    )
+
+    vi.mocked(mockWallet.deploy).mockResolvedValue({
+      chainId: 1,
+      success: true,
+      receipt: undefined,
+    })
+
+    await provider.createWallet({
+      signers: [mockSigner.address],
+      signer: mockSigner,
+    })
+
+    expect(createWalletSpy).toHaveBeenCalled()
+    const callArg = createWalletSpy.mock.calls[0]?.[0]
+    expect(callArg?.attributionSuffix).toBe(expectedSuffix)
+  })
+
+  it('passes attributionSuffix from constructor into getWallet', async () => {
+    const attributionSeed = 'campaign-123'
+    const expectedSuffix =
+      DefaultSmartWalletProvider.computeAttributionSuffix(attributionSeed)
+    const provider = new DefaultSmartWalletProvider(
+      mockChainManager,
+      mockLendProvider,
+      attributionSeed,
+    )
+
+    await provider.getWallet({
+      walletAddress: getRandomAddress(),
+      signer: mockSigner,
+      signers: [mockSigner.address],
+    })
+
+    expect(createWalletSpy).toHaveBeenCalled()
+    const callArg = createWalletSpy.mock.calls[0]?.[0]
+    expect(callArg?.attributionSuffix).toBe(expectedSuffix)
+  })
+})