@eth-optimism/actions-sdk 0.0.2

package/src/lend/core/LendProvider.ts

@@ -0,0 +1,311 @@
+import type { Address } from 'viem'
+import { parseUnits } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { Asset } from '@/types/asset.js'
+import type {
+  BaseLendConfig,
+  ClosePositionParams,
+  GetLendMarketParams,
+  GetLendMarketsParams,
+  GetMarketBalanceParams,
+  LendClosePositionParams,
+  LendMarket,
+  LendMarketConfig,
+  LendMarketId,
+  LendMarketPosition,
+  LendOpenPositionInternalParams,
+  LendOpenPositionParams,
+  LendTransaction,
+} from '@/types/lend/index.js'
+import { validateMarketAsset } from '@/utils/markets.js'
+
+/**
+ * Lending provider abstract class
+ * @description Base class for lending provider implementations
+ */
+export abstract class LendProvider<
+  TConfig extends BaseLendConfig = BaseLendConfig,
+> {
+  /** Lending provider configuration */
+  protected readonly _config: TConfig
+
+  /**
+   * Supported chain IDs
+   * @description Array of chain IDs that this provider supports
+   */
+  protected abstract readonly SUPPORTED_CHAIN_IDS: readonly number[]
+
+  /**
+   * Create a new lending provider
+   * @param config - Provider-specific lending configuration
+   */
+  protected constructor(config: TConfig) {
+    this._config = config
+  }
+
+  public get config(): TConfig {
+    return this._config
+  }
+
+  /**
+   * Get supported chain IDs
+   * @description Returns an array of chain IDs that this provider supports
+   * @returns Array of supported chain IDs
+   */
+  supportedChainIds(): number[] {
+    return [...this.SUPPORTED_CHAIN_IDS]
+  }
+
+  /**
+   * Open a lending position
+   * @param amount - Amount to lend (human-readable number)
+   * @param asset - Asset to lend
+   * @param marketId - Market identifier containing address and chainId
+   * @param options - Optional lending configuration
+   * @returns Promise resolving to lending transaction details
+   */
+  async openPosition(params: LendOpenPositionParams): Promise<LendTransaction> {
+    if (!params.walletAddress) {
+      throw new Error('walletAddress is required')
+    }
+
+    this.validateProviderSupported(params.marketId.chainId)
+    this.validateConfigSupported(params.marketId)
+
+    // Convert human-readable amount to wei using the asset's decimals
+    const amountWei = parseUnits(
+      params.amount.toString(),
+      params.asset.metadata.decimals,
+    )
+
+    return this._openPosition({
+      ...params,
+      amountWei,
+      walletAddress: params.walletAddress,
+    })
+  }
+
+  /**
+   * Get detailed market information
+   * @param address - Market contract address
+   * @param chainId - Chain ID where the market exists
+   * @returns Promise resolving to market information
+   */
+  async getMarket(params: GetLendMarketParams): Promise<LendMarket> {
+    const marketId: LendMarketId = {
+      address: params.address,
+      chainId: params.chainId,
+    }
+
+    this.validateProviderSupported(params.chainId)
+    this.validateConfigSupported(marketId)
+    return this._getMarket(marketId)
+  }
+
+  /**
+   * Get list of available lending markets
+   * @param params - Optional filtering parameters
+   * @returns Promise resolving to array of market information
+   */
+  async getMarkets(params: GetLendMarketsParams = {}): Promise<LendMarket[]> {
+    if (params.chainId !== undefined)
+      this.validateProviderSupported(params.chainId)
+
+    const filteredMarkets = this.filterMarketConfigs(
+      params.chainId,
+      params.asset,
+    )
+
+    return this._getMarkets({
+      asset: params.asset,
+      chainId: params.chainId,
+      markets: params.markets || filteredMarkets,
+    })
+  }
+
+  /**
+   * Get position information for a wallet
+   * @param walletAddress - User wallet address to check position for
+   * @param marketId - Market identifier (required)
+   * @param asset - Asset filter (not yet supported)
+   * @returns Promise resolving to position information
+   */
+  async getPosition(
+    walletAddress: Address,
+    marketId?: LendMarketId,
+    asset?: Asset,
+  ): Promise<LendMarketPosition> {
+    // For now, require marketId (asset-only and empty params not yet supported)
+    if (!marketId) {
+      throw new Error(
+        'marketId is required. Querying all positions or by asset is not yet supported.',
+      )
+    }
+
+    if (asset) {
+      throw new Error(
+        'Filtering by asset is not yet supported. Please provide only marketId.',
+      )
+    }
+
+    this.validateProviderSupported(marketId.chainId)
+    this.validateConfigSupported(marketId)
+
+    return this._getPosition({ marketId, walletAddress })
+  }
+
+  /**
+   * Close a lending position (withdraw assets from a market)
+   * @param amount - Amount to withdraw (human-readable number)
+   * @param asset - Asset to withdraw (optional, validated against marketId)
+   * @param marketId - Market identifier containing address and chainId
+   * @param walletAddress - Wallet address for receiving assets and as owner
+   * @param options - Optional withdrawal configuration
+   * @returns Promise resolving to withdrawal transaction details
+   */
+  async closePosition(params: ClosePositionParams): Promise<LendTransaction> {
+    if (!params.walletAddress) {
+      throw new Error('walletAddress is required')
+    }
+
+    this.validateProviderSupported(params.marketId.chainId)
+    this.validateConfigSupported(params.marketId)
+
+    const market = await this.getMarket({
+      address: params.marketId.address,
+      chainId: params.marketId.chainId,
+    })
+
+    if (params.asset) {
+      validateMarketAsset(market, params.asset)
+    }
+
+    const assetMetadata = params.asset?.metadata
+    if (!assetMetadata) {
+      throw new Error('Asset metadata is required for decimal conversion')
+    }
+
+    // Convert human-readable amount to wei using the asset's decimals
+    const amountWei = parseUnits(
+      params.amount.toString(),
+      assetMetadata.decimals,
+    )
+
+    return this._closePosition({
+      asset: params.asset,
+      amount: amountWei,
+      marketId: params.marketId,
+      walletAddress: params.walletAddress,
+      options: params.options,
+    })
+  }
+
+  /**
+   * Check if a chain is supported by this lending provider
+   * @param chainId - Chain ID to check
+   * @returns true if chain is supported, false otherwise
+   */
+  protected isChainSupported(chainId: number): boolean {
+    return this.SUPPORTED_CHAIN_IDS.includes(chainId)
+  }
+
+  /**
+   * Validate that a chainId is supported for lending operations
+   * @param chainId - Chain ID to validate
+   * @throws Error if chain is not supported
+   */
+  protected validateProviderSupported(chainId: number): void {
+    if (!this.isChainSupported(chainId)) {
+      throw new Error(
+        `Chain ${chainId} is not supported. Supported chains: ${this.SUPPORTED_CHAIN_IDS.join(', ')}`,
+      )
+    }
+  }
+
+  /**
+   * Validate that a market is in the config's market allowlist
+   * @param marketId - Market identifier containing address and chainId
+   * @throws Error if market allowlist is configured but market is not in it
+   */
+  protected validateConfigSupported(marketId: LendMarketId): void {
+    if (
+      !this._config.marketAllowlist ||
+      this._config.marketAllowlist.length === 0
+    ) {
+      return
+    }
+
+    const foundMarket = this._config.marketAllowlist.find(
+      (allowedMarket) =>
+        allowedMarket.address.toLowerCase() ===
+          marketId.address.toLowerCase() &&
+        allowedMarket.chainId === marketId.chainId,
+    )
+
+    if (!foundMarket) {
+      throw new Error(
+        `Market ${marketId.address} on chain ${marketId.chainId} is not in the market allowlist`,
+      )
+    }
+  }
+
+  /**
+   * Helper method to filter market configurations
+   * @param chainId - Chain ID to filter by
+   * @param asset - Asset to filter by
+   * @returns Filtered market configurations
+   */
+  private filterMarketConfigs(
+    chainId?: SupportedChainId,
+    asset?: Asset,
+  ): LendMarketConfig[] {
+    let configs = this._config.marketAllowlist || []
+    if (chainId !== undefined)
+      configs = configs.filter((m) => m.chainId === chainId)
+    if (asset !== undefined) configs = configs.filter((m) => m.asset === asset)
+    return configs
+  }
+
+  /**
+   * Abstract methods that must be implemented by providers
+   */
+
+  /**
+   * Provider implementation of openPosition method
+   * @description Must be implemented by providers
+   */
+  protected abstract _openPosition(
+    params: LendOpenPositionInternalParams,
+  ): Promise<LendTransaction>
+
+  /**
+   * Provider implementation of getMarket method
+   * @description Must be implemented by providers
+   */
+  protected abstract _getMarket(marketId: LendMarketId): Promise<LendMarket>
+
+  /**
+   * Provider implementation of getMarkets method
+   * @description Must be implemented by providers
+   */
+  protected abstract _getMarkets(
+    params: GetLendMarketsParams,
+  ): Promise<LendMarket[]>
+
+  /**
+   * Provider implementation of getPosition method
+   * @description Must be implemented by providers
+   */
+  protected abstract _getPosition(
+    params: GetMarketBalanceParams,
+  ): Promise<LendMarketPosition>
+
+  /**
+   * Provider implementation of closePosition method
+   * @description Must be implemented by providers
+   */
+  protected abstract _closePosition(
+    params: LendClosePositionParams,
+  ): Promise<LendTransaction>
+}

package/src/lend/core/__tests__/LendProvider.test.ts

@@ -0,0 +1,305 @@
+import type { Address } from 'viem'
+import { describe, expect, it } from 'vitest'
+
+import { MockUSDCAsset } from '@/test/MockAssets.js'
+import { MockLendProvider } from '@/test/MockLendProvider.js'
+import type {
+  LendConfig,
+  LendMarketConfig,
+  LendMarketId,
+} from '@/types/lend/index.js'
+
+// Test helper class that exposes protected validation methods as public
+class TestLendProvider extends MockLendProvider {
+  public validateProviderSupported(chainId: number): void {
+    return super.validateProviderSupported(chainId)
+  }
+
+  public validateConfigSupported(marketId: LendMarketId): void {
+    return super.validateConfigSupported(marketId)
+  }
+
+  public isChainSupported(chainId: number): boolean {
+    return super.isChainSupported(chainId)
+  }
+}
+
+describe('LendProvider', () => {
+  describe('constructor and configuration', () => {
+    it('should initialize with basic config', () => {
+      const config: LendConfig = {
+        provider: 'morpho',
+        defaultSlippage: 100,
+      }
+
+      const provider = new MockLendProvider(config)
+      expect(provider).toBeDefined()
+      expect(provider.supportedChainIds()).toContain(84532)
+    })
+
+    it('should use default slippage when not provided', () => {
+      const config: LendConfig = { provider: 'morpho' }
+      const provider = new MockLendProvider(config)
+
+      expect(provider.config.defaultSlippage || 50).toBe(50)
+    })
+
+    it('should use custom default slippage when provided', () => {
+      const config: LendConfig = {
+        provider: 'morpho',
+        defaultSlippage: 200,
+      }
+      const provider = new MockLendProvider(config)
+
+      expect(provider.config.defaultSlippage).toBe(200)
+    })
+
+    it('should store market allowlist when provided', () => {
+      const mockMarket: LendMarketConfig = {
+        address: '0x1234' as Address,
+        chainId: 84532,
+        name: 'Test Market',
+        asset: {
+          address: { 84532: '0xUSC' as Address },
+          metadata: {
+            decimals: 6,
+            name: 'USD Coin',
+            symbol: 'USDC',
+          },
+          type: 'erc20',
+        },
+        lendProvider: 'morpho',
+      }
+
+      const config: LendConfig = {
+        provider: 'morpho',
+        marketAllowlist: [mockMarket],
+      }
+
+      const provider = new MockLendProvider(config)
+      expect(provider.config.marketAllowlist).toEqual([mockMarket])
+    })
+  })
+
+  describe('abstract methods implementation', () => {
+    it('should implement getMarket method', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const marketId: LendMarketId = {
+        address: '0x1234' as Address,
+        chainId: 84532,
+      }
+
+      const market = await provider.getMarket(marketId)
+      expect(market.marketId.chainId).toBe(84532)
+      expect(market.name).toBe('Mock Market')
+      expect(market.apy.total).toBe(0.05)
+    })
+
+    it('should accept LendMarketConfig and extract address/chainId', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const mockMarket: LendMarketConfig = {
+        address: '0x5678' as Address,
+        chainId: 84532,
+        name: 'Test Config Market',
+        asset: MockUSDCAsset,
+        lendProvider: 'morpho',
+      }
+
+      const market = await provider.getMarket(mockMarket)
+      expect(market.marketId.chainId).toBe(84532)
+      expect(market.marketId.address).toBe('0x5678')
+      expect(market.name).toBe('Mock Market')
+    })
+
+    it('should implement getMarkets method', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const markets = await provider.getMarkets()
+
+      expect(Array.isArray(markets)).toBe(true)
+      expect(markets).toHaveLength(1)
+      expect(markets[0].name).toBe('Mock Market')
+    })
+
+    it('should accept optional filter parameters for getMarkets', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const markets = await provider.getMarkets({ chainId: 84532 })
+
+      expect(Array.isArray(markets)).toBe(true)
+      expect(markets).toHaveLength(1)
+    })
+
+    it('should accept asset filtering parameter', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const mockAsset = {
+        metadata: { symbol: 'USDC', name: 'USD Coin' },
+        address: { 84532: '0x123' as Address },
+      } as any
+
+      const markets = await provider.getMarkets({ asset: mockAsset })
+      expect(Array.isArray(markets)).toBe(true)
+    })
+
+    it('should implement getPosition method', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const position = await provider.getPosition('0x5678' as Address, {
+        address: '0x1234' as Address,
+        chainId: 84532 as const,
+      })
+
+      expect(position.balance).toBe(500000n)
+      expect(position.shares).toBe(500000n)
+      expect(position.marketId.chainId).toBe(84532)
+    })
+
+    it('should implement closePosition method', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const result = await provider.closePosition({
+        amount: 100,
+        marketId: { address: '0x1234' as Address, chainId: 84532 as const },
+        walletAddress: '0x5678' as Address,
+      })
+
+      expect(result.amount).toBe(100n)
+      expect(result.marketId).toBe('0x1234')
+      expect(typeof result.transactionData).toBe('object')
+    })
+
+    it('should implement withdraw method', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const result = await provider.withdraw(
+        '0x0000000000000000000000000000000000000001' as Address,
+        500n,
+        84532,
+        'market-2',
+      )
+
+      expect(result.amount).toBe(500n)
+      expect(result.marketId).toBe('market-2')
+    })
+
+    it('should implement openPosition method', async () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const mockAsset = {
+        address: { 84532: '0x123' as Address },
+        metadata: { symbol: 'USDC', name: 'USD Coin', decimals: 6 },
+        type: 'erc20' as const,
+      }
+
+      const result = await provider.openPosition({
+        amount: 1000,
+        asset: mockAsset,
+        marketId: { address: '0x1234' as Address, chainId: 84532 },
+        walletAddress: '0x5678' as Address,
+      })
+
+      expect(result.amount).toBe(1000000000n)
+      expect(result.asset).toBe('0x123')
+      expect(result.marketId).toBe('0x1234')
+      expect(result.apy).toBe(0.05)
+    })
+  })
+
+  describe('supportedChainIds', () => {
+    it('should return array of supported chain IDs', () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      const chainIds = provider.supportedChainIds()
+
+      expect(Array.isArray(chainIds)).toBe(true)
+      expect(chainIds).toContain(84532)
+      expect(chainIds.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe('validation', () => {
+    it('should call validation for unsupported chainId', () => {
+      const provider = new TestLendProvider({ provider: 'morpho' })
+
+      expect(() => {
+        provider.validateProviderSupported(999)
+      }).toThrow('Chain 999 is not supported')
+    })
+
+    it('should call validation for market allowlist', () => {
+      const allowedMarket: LendMarketConfig = {
+        address: '0x1234' as Address,
+        chainId: 84532,
+        name: 'Allowed Market',
+        asset: {
+          address: { 84532: '0xUSC' as Address },
+          metadata: { decimals: 6, name: 'USD Coin', symbol: 'USDC' },
+          type: 'erc20',
+        },
+        lendProvider: 'morpho',
+      }
+
+      const provider = new TestLendProvider({
+        provider: 'morpho',
+        marketAllowlist: [allowedMarket],
+      })
+
+      expect(() => {
+        provider.validateConfigSupported({
+          address: '0x1234' as Address,
+          chainId: 84532,
+        })
+      }).not.toThrow()
+
+      expect(() => {
+        provider.validateConfigSupported({
+          address: '0x9999' as Address,
+          chainId: 84532,
+        })
+      }).toThrow('not in the market allowlist')
+    })
+
+    it('should validate chain support correctly', () => {
+      const provider = new TestLendProvider({ provider: 'morpho' })
+
+      expect(provider.isChainSupported(84532)).toBe(true)
+      expect(provider.isChainSupported(999)).toBe(false)
+    })
+  })
+
+  describe('public getters', () => {
+    it('should provide access to defaultSlippage via getter', () => {
+      const config: LendConfig = {
+        provider: 'morpho',
+        defaultSlippage: 75,
+      }
+      const provider = new MockLendProvider(config)
+
+      expect(provider.config.defaultSlippage).toBe(75)
+    })
+
+    it('should provide access to marketAllowlist via getter', () => {
+      const mockMarket: LendMarketConfig = {
+        address: '0xabc' as Address,
+        chainId: 84532,
+        name: 'Market ABC',
+        asset: {
+          address: { 84532: '0xdef' as Address },
+          metadata: {
+            decimals: 18,
+            name: 'Test Token',
+            symbol: 'TEST',
+          },
+          type: 'erc20',
+        },
+        lendProvider: 'morpho',
+      }
+
+      const config: LendConfig = {
+        provider: 'morpho',
+        marketAllowlist: [mockMarket],
+      }
+      const provider = new MockLendProvider(config)
+
+      expect(provider.config.marketAllowlist).toEqual([mockMarket])
+    })
+
+    it('should return undefined for marketAllowlist when not provided', () => {
+      const provider = new MockLendProvider({ provider: 'morpho' })
+      expect(provider.config.marketAllowlist).toBeUndefined()
+    })
+  })
+})

package/src/lend/index.ts

@@ -0,0 +1,2 @@
+export { LendProvider } from '@/lend/core/LendProvider.js'
+export { MorphoLendProvider } from '@/lend/providers/morpho/MorphoLendProvider.js'

package/src/lend/namespaces/ActionsLendNamespace.ts

@@ -0,0 +1,26 @@
+import type { LendProvider } from '@/lend/core/LendProvider.js'
+import type { BaseLendConfig, LendConfig } from '@/types/lend/index.js'
+
+/**
+ * Actions Lend Namespace
+ * @description Read-only lending operations available on actions.lend
+ */
+export class ActionsLendNamespace<TConfig extends BaseLendConfig = LendConfig> {
+  constructor(protected readonly provider: LendProvider<TConfig>) {}
+
+  get config(): TConfig {
+    return this.provider.config
+  }
+
+  // Bind to the LendProvider's methods and carry types
+
+  getMarkets = (...args: Parameters<LendProvider<TConfig>['getMarkets']>) =>
+    this.provider.getMarkets(...args)
+
+  getMarket = (...args: Parameters<LendProvider<TConfig>['getMarket']>) =>
+    this.provider.getMarket(...args)
+
+  supportedChainIds = (
+    ...args: Parameters<LendProvider<TConfig>['supportedChainIds']>
+  ) => this.provider.supportedChainIds(...args)
+}