@eth-optimism/actions-sdk 0.0.2

package/src/actions.ts

@@ -0,0 +1,190 @@
+import { DEFAULT_ACTIONS_CONFIG } from '@/constants/config.js'
+import { MorphoLendProvider } from '@/lend/index.js'
+import { ActionsLendNamespace } from '@/lend/namespaces/ActionsLendNamespace.js'
+import { ChainManager } from '@/services/ChainManager.js'
+import type { ActionsConfig } from '@/types/actions.js'
+import type { LendConfig, LendProvider } from '@/types/lend/index.js'
+import { WalletNamespace } from '@/wallet/core/namespace/WalletNamespace.js'
+import type { HostedWalletProvider } from '@/wallet/core/providers/hosted/abstract/HostedWalletProvider.js'
+import type { HostedWalletProviderRegistry } from '@/wallet/core/providers/hosted/registry/HostedWalletProviderRegistry.js'
+import type { HostedWalletProvidersSchema } from '@/wallet/core/providers/hosted/types/index.js'
+import type { SmartWalletProvider } from '@/wallet/core/providers/smart/abstract/SmartWalletProvider.js'
+import { DefaultSmartWalletProvider } from '@/wallet/core/providers/smart/default/DefaultSmartWalletProvider.js'
+import { WalletProvider } from '@/wallet/core/providers/WalletProvider.js'
+
+/**
+ * Main Actions SDK class
+ * @description Core implementation of the Actions SDK
+ */
+export class Actions<
+  THostedWalletProviderConfigKeys extends string,
+  THostedWalletProvidersSchema extends HostedWalletProvidersSchema<
+    THostedWalletProviderConfigKeys,
+    {
+      [K in THostedWalletProviderConfigKeys]: HostedWalletProvider<
+        K,
+        { [K in THostedWalletProviderConfigKeys]: unknown }
+      >
+    },
+    { [K in THostedWalletProviderConfigKeys]: unknown },
+    { [K in THostedWalletProviderConfigKeys]: unknown }
+  >,
+  THostedWalletProviderType extends THostedWalletProviderConfigKeys,
+> {
+  public readonly wallet: WalletNamespace<
+    THostedWalletProviderType,
+    THostedWalletProvidersSchema['providerToActionsOptions'],
+    THostedWalletProvidersSchema['providerInstances'][THostedWalletProviderType],
+    SmartWalletProvider
+  >
+  private chainManager: ChainManager
+  private _lend?: ActionsLendNamespace<LendConfig>
+  private _lendProvider?: LendProvider<LendConfig>
+  private hostedWalletProvider!: THostedWalletProvidersSchema['providerInstances'][THostedWalletProviderType]
+  private smartWalletProvider!: SmartWalletProvider
+  private hostedWalletProviderRegistry: HostedWalletProviderRegistry<
+    THostedWalletProvidersSchema['providerInstances'],
+    THostedWalletProvidersSchema['providerConfigs'],
+    THostedWalletProvidersSchema['providerTypes']
+  >
+  constructor(
+    config: ActionsConfig<
+      THostedWalletProviderType,
+      THostedWalletProvidersSchema['providerConfigs']
+    >,
+    deps: {
+      hostedWalletProviderRegistry: HostedWalletProviderRegistry<
+        THostedWalletProvidersSchema['providerInstances'],
+        THostedWalletProvidersSchema['providerConfigs'],
+        THostedWalletProvidersSchema['providerTypes']
+      >
+    },
+  ) {
+    this.chainManager = new ChainManager(config.chains)
+    this.hostedWalletProviderRegistry = deps.hostedWalletProviderRegistry
+
+    // Create lending provider if configured
+    if (config.lend) {
+      if (config.lend.provider === 'morpho') {
+        this._lendProvider = new MorphoLendProvider(
+          {
+            ...config.lend,
+            defaultSlippage:
+              config.lend.defaultSlippage ??
+              DEFAULT_ACTIONS_CONFIG.lend.defaultSlippage,
+          },
+          this.chainManager,
+        )
+
+        // Create read-only lend namespace
+        this._lend = new ActionsLendNamespace(this._lendProvider!)
+      } else {
+        throw new Error(`Unsupported lending provider: ${config.lend.provider}`)
+      }
+    }
+
+    this.wallet = this.createWalletNamespace(config.wallet)
+  }
+
+  /**
+   * Get lend operations interface
+   * @description Access to lending operations like markets and vault information.
+   * Throws an error if no lend provider is configured in ActionsConfig.
+   * @returns ActionsLendNamespace for lending operations
+   * @throws Error if lend provider not configured
+   */
+  get lend(): ActionsLendNamespace<LendConfig> {
+    if (!this._lend) {
+      throw new Error(
+        'Lend provider not configured. Please add lend configuration to ActionsConfig.',
+      )
+    }
+    return this._lend
+  }
+
+  /**
+   * Get the lend provider instance
+   * @returns LendProvider instance if configured, undefined otherwise
+   */
+  get lendProvider(): LendProvider<LendConfig> | undefined {
+    return this._lendProvider
+  }
+
+  /**
+   * Create the wallet provider instance
+   * @param config - Wallet configuration
+   * @returns WalletProvider instance
+   */
+  private createWalletProvider(
+    config: ActionsConfig<
+      THostedWalletProviderType,
+      THostedWalletProvidersSchema['providerConfigs']
+    >['wallet'],
+  ): WalletProvider<
+    THostedWalletProviderType,
+    THostedWalletProvidersSchema['providerToActionsOptions'],
+    THostedWalletProvidersSchema['providerInstances'][THostedWalletProviderType],
+    SmartWalletProvider
+  > {
+    const hostedWalletProviderConfig = config.hostedWalletConfig.provider
+    const factory = this.hostedWalletProviderRegistry.getFactory(
+      hostedWalletProviderConfig.type,
+    )
+    const options = (
+      'config' in hostedWalletProviderConfig
+        ? hostedWalletProviderConfig.config
+        : undefined
+    ) as unknown
+    if (!factory.validateOptions(options)) {
+      throw new Error(
+        `Invalid options for hosted wallet provider: ${hostedWalletProviderConfig.type}`,
+      )
+    }
+    this.hostedWalletProvider = factory.create(
+      { chainManager: this.chainManager, lendProvider: this.lendProvider },
+      options,
+    )
+
+    if (
+      !config.smartWalletConfig ||
+      config.smartWalletConfig.provider.type === 'default'
+    ) {
+      this.smartWalletProvider = new DefaultSmartWalletProvider(
+        this.chainManager,
+        this.lendProvider,
+        config.smartWalletConfig.provider.attributionSuffix,
+      )
+    } else {
+      throw new Error(
+        `Unsupported smart wallet provider: ${config.smartWalletConfig.provider.type}`,
+      )
+    }
+
+    const walletProvider = new WalletProvider(
+      this.hostedWalletProvider,
+      this.smartWalletProvider,
+    )
+
+    return walletProvider
+  }
+
+  /**
+   * Create the wallet namespace instance
+   * @param config - Wallet configuration
+   * @returns WalletNamespace instance
+   */
+  private createWalletNamespace(
+    config: ActionsConfig<
+      THostedWalletProviderType,
+      THostedWalletProvidersSchema['providerConfigs']
+    >['wallet'],
+  ) {
+    const walletProvider = this.createWalletProvider(config)
+    return new WalletNamespace<
+      THostedWalletProviderType,
+      THostedWalletProvidersSchema['providerToActionsOptions'],
+      THostedWalletProvidersSchema['providerInstances'][THostedWalletProviderType],
+      SmartWalletProvider
+    >(walletProvider)
+  }
+}

package/src/constants/assets.ts

@@ -0,0 +1,20 @@
+import type { Address } from 'viem'
+import { base, baseSepolia, mainnet, unichain } from 'viem/chains'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { Asset } from '@/types/asset.js'
+
+export const ETH: Asset = {
+  address: {
+    [mainnet.id]: '0x0000000000000000000000000000000000000000',
+    [unichain.id]: '0x0000000000000000000000000000000000000000',
+    [base.id]: '0x0000000000000000000000000000000000000000',
+    [baseSepolia.id]: '0x0000000000000000000000000000000000000000',
+  } satisfies Record<SupportedChainId, Address>,
+  metadata: {
+    decimals: 18,
+    name: 'Ethereum',
+    symbol: 'ETH',
+  },
+  type: 'native',
+}

package/src/constants/config.ts

@@ -0,0 +1,9 @@
+/**
+ * Default SDK configuration values
+ */
+export const DEFAULT_ACTIONS_CONFIG = {
+  lend: {
+    /** Default slippage tolerance for lending operations (in basis points: 50 = 0.5%) */
+    defaultSlippage: 50,
+  },
+} as const

package/src/constants/supportedChains.ts

@@ -0,0 +1,10 @@
+import { base, baseSepolia, mainnet, unichain } from 'viem/chains'
+
+export const SUPPORTED_CHAIN_IDS = [
+  mainnet.id,
+  unichain.id,
+  base.id,
+  baseSepolia.id,
+] as const
+
+export type SupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number]

package/src/core/asset/__mocks__/mockAsset.ts

@@ -0,0 +1,13 @@
+import { getRandomAddress } from '@/test/utils.js'
+import type { Asset } from '@/types/asset.js'
+
+/**
+ * Creates a mock USDC asset for testing
+ */
+export function createMockUSDCAsset(chainId: number = 130): Asset {
+  return {
+    address: { [chainId]: getRandomAddress() },
+    metadata: { symbol: 'USDC', name: 'USD Coin', decimals: 6 },
+    type: 'erc20' as const,
+  }
+}

package/src/core/error/errors.ts

@@ -0,0 +1,27 @@
+import type { TransactionReceipt } from 'viem'
+
+/**
+ * Error for a transaction that was included on-chain but reverted
+ * @description Thrown when a transaction makes it into a block (i.e. has a
+ * confirmed receipt) yet the EVM execution failed. The full
+ * {@link TransactionReceipt | transaction receipt} is attached for
+ * post-mortem analysis (status, logs, gas usage, etc.).
+ */
+export class TransactionConfirmedButRevertedError extends Error {
+  /** Full receipt returned by the node for the reverted transaction */
+  receipt: TransactionReceipt
+
+  /**
+   * Create an instance of TransactionConfirmedButRevertedError
+   * @param message - Human-readable description of the failure
+   * @param receipt - Confirmed transaction receipt indicating a revert
+   */
+  constructor(message: string, receipt: TransactionReceipt) {
+    if (!message || typeof message !== 'string') {
+      throw new Error('"message" must be a nonempty string.')
+    }
+
+    super(message)
+    this.receipt = receipt
+  }
+}

package/src/core/utils/__tests__/retryOnStaleRead.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { retryOnStaleRead } from '@/core/utils/retryOnStaleRead.js'
+
+describe('retryOnStaleRead', () => {
+  it('returns immediately when value is fresh', async () => {
+    const read = vi.fn().mockResolvedValue(42)
+    const isStale = (v: number) => v < 0
+
+    const result = await retryOnStaleRead(read, isStale)
+
+    expect(result).toBe(42)
+    expect(read).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries once after delay and returns fresh value', async () => {
+    vi.useFakeTimers()
+
+    const read = vi
+      .fn<[], Promise<number>>()
+      .mockResolvedValueOnce(-1) // stale
+      .mockResolvedValueOnce(7) // fresh
+    const isStale = (v: number) => v === -1
+
+    const delayMs = 2000
+    const retries = 1
+    const promise = retryOnStaleRead(read, isStale, { retries, delayMs: 2000 })
+
+    await vi.advanceTimersByTimeAsync(delayMs * (retries + 1))
+    const result = await promise
+
+    expect(read).toHaveBeenCalledTimes(2)
+    expect(result).toBe(7)
+
+    vi.useRealTimers()
+  })
+
+  it('after all retries, returns last read value even if stale', async () => {
+    vi.useFakeTimers()
+
+    const read = vi.fn().mockResolvedValue(-1)
+    const isStale = (v: number) => v === -1
+
+    const delayMs = 1000
+    const retries = 2
+    const promise = retryOnStaleRead(read, isStale, { retries, delayMs: 1000 })
+
+    await vi.advanceTimersByTimeAsync(delayMs * (retries + 1))
+    const result = await promise
+
+    expect(read).toHaveBeenCalledTimes(3)
+    expect(result).toBe(-1)
+
+    vi.useRealTimers()
+  })
+})

package/src/core/utils/retryOnStaleRead.ts

@@ -0,0 +1,39 @@
+/**
+ * Retry a read operation to mitigate eventual consistency/race conditions
+ * @description Useful for onchain reads that may temporarily return stale data
+ * right after a write (e.g., before state is propagated to the queried node).
+ * The read function is invoked, and if the result is deemed stale by the
+ * provided predicate (or the read throws), it waits and retries up to `retries` times.
+ */
+export async function retryOnStaleRead<T>(
+  read: () => Promise<T>,
+  isStale: (value: T) => boolean,
+  options?: {
+    /** Number of retry attempts if the result is stale. Default: 1 */
+    retries?: number
+    /** Delay in milliseconds between attempts. Default: 2000 */
+    delayMs?: number
+  },
+): Promise<T> {
+  const retries = options?.retries ?? 1
+  const delayMs = options?.delayMs ?? 2000
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (attempt === retries) {
+      break
+    }
+
+    try {
+      const result = await read()
+      if (!isStale(result)) return result
+    } catch {
+      // Treat errors as potentially stale reads; retry below
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, delayMs))
+  }
+
+  // Final attempt already performed and was stale; perform one last read to return whatever it is
+  // to the caller (stale or not), so the caller can decide what to do.
+  return await read()
+}

package/src/index.node.ts

@@ -0,0 +1,4 @@
+export * from '@/index.js'
+export type { NodeActionsConfig } from '@/nodeActionsFactory.js'
+export { createActions } from '@/nodeActionsFactory.js'
+export * from '@/wallet/node/index.js'

package/src/index.react.ts

@@ -0,0 +1,4 @@
+export * from '@/index.js'
+export type { ReactActionsConfig } from '@/reactActionsFactory.js'
+export { createActions } from '@/reactActionsFactory.js'
+export * from '@/wallet/react/index.js'

package/src/index.ts

@@ -0,0 +1,35 @@
+export type { Actions } from '@/actions.js'
+export { ETH } from '@/constants/assets.js'
+export type { SupportedChainId } from '@/constants/supportedChains.js'
+export * from '@/core/error/errors.js'
+export { LendProvider, MorphoLendProvider } from '@/lend/index.js'
+export {
+  getTokenAddress,
+  getTokenBySymbol,
+  SUPPORTED_TOKENS,
+} from '@/supported/tokens.js'
+export type {
+  ActionsConfig,
+  ApyBreakdown,
+  Asset,
+  BaseLendConfig,
+  EOATransactionReceipt,
+  LendConfig,
+  LendMarket,
+  LendMarketConfig,
+  LendMarketId,
+  LendMarketMetadata,
+  LendMarketPosition,
+  LendMarketSupply,
+  LendOptions,
+  LendTransaction,
+  LendTransactionReceipt,
+  MorphoLendConfig,
+  TokenBalance,
+  TransactionData,
+  UserOperationTransactionReceipt,
+  WalletConfig,
+} from '@/types/index.js'
+export { getAssetAddress, isAssetSupportedOnChain } from '@/utils/assets.js'
+export { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
+export { SmartWallet } from '@/wallet/core/wallets/smart/abstract/SmartWallet.js'

package/src/lend/__mocks__/mockLendTransaction.ts

@@ -0,0 +1,47 @@
+import type { Address } from 'viem'
+
+import type { LendTransaction, TransactionData } from '@/types/lend/index.js'
+
+/**
+ * Creates a mock lend transaction for testing openPosition
+ */
+export function createMockOpenTransaction(params: {
+  amount: bigint
+  asset: Address
+  marketId: Address
+  approval?: TransactionData
+  openPosition?: TransactionData
+}): LendTransaction {
+  return {
+    amount: params.amount,
+    asset: params.asset,
+    marketId: params.marketId,
+    apy: 0.05,
+    transactionData: {
+      approval: params.approval,
+      openPosition: params.openPosition,
+    },
+    slippage: 50,
+  }
+}
+
+/**
+ * Creates a mock lend transaction for testing closePosition
+ */
+export function createMockCloseTransaction(params: {
+  amount: bigint
+  asset: Address
+  marketId: Address
+  closePosition: TransactionData
+}): LendTransaction {
+  return {
+    amount: params.amount,
+    asset: params.asset,
+    marketId: params.marketId,
+    apy: 0.05,
+    transactionData: {
+      closePosition: params.closePosition,
+    },
+    slippage: 50,
+  }
+}