@eth-optimism/actions-sdk 0.1.0 → 0.3.0

package/src/types/actions.ts

@@ -1,21 +1,35 @@
+import type { UniswapSwapProviderConfig } from '@/swap/providers/uniswap/types.js'
 import type { Asset } from '@/types/asset.js'
 import type { ChainConfig } from '@/types/chain.js'
 import type { LendProviderConfig } from '@/types/lend/index.js'
+import type { SwapProviderConfig } from '@/types/swap/index.js'
 import type { ProviderSpec } from '@/wallet/core/providers/hosted/types/index.js'
 
-// Re-export LendProviderConfig for convenience
-export type { LendProviderConfig }
+// Re-export provider configs for convenience
+export type { LendProviderConfig, SwapProviderConfig }
+
+/** Require at least one property to be defined */
+type RequireAtLeastOne<T> = {
+  [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
+}[keyof T]
 
 /**
- * Lending configuration
- * @description Configuration for all lending providers
+ * Lending configuration — at least one provider must be configured
  */
-export interface LendConfig {
+export type LendConfig = RequireAtLeastOne<{
   /** Morpho lending provider configuration */
   morpho?: LendProviderConfig
   /** Aave lending provider configuration */
   aave?: LendProviderConfig
-}
+}>
+
+/**
+ * Swap configuration — at least one provider must be configured
+ */
+export type SwapConfig = RequireAtLeastOne<{
+  /** Uniswap swap provider configuration */
+  uniswap?: UniswapSwapProviderConfig
+}>
 
 /**
  * Network configuration for lending providers
@@ -49,6 +63,8 @@ export interface ActionsConfig<
   wallet: WalletConfig<THostedWalletProviderType, TConfigMap>
   /** Lending providers configuration (optional) */
   lend?: LendConfig
+  /** Swap providers configuration (optional) */
+  swap?: SwapConfig
   /** Assets configuration (optional) */
   assets?: AssetsConfig
   /** Chains to use for the SDK */

package/src/types/asset.ts

@@ -6,8 +6,8 @@ import type { SupportedChainId } from '@/constants/supportedChains.js'
  * Asset type inspired by EIP 7811 but adapted for multi-chain asset definitions
  */
 export interface Asset {
-  /** Multi-chain address mapping */
-  address: Partial<Record<SupportedChainId, Address>>
+  /** Multi-chain address mapping. Native assets use 'native' string to prevent accidental contract calls. */
+  address: Partial<Record<SupportedChainId, Address | 'native'>>
   /** Asset metadata */
   metadata: {
     decimals: number
@@ -28,7 +28,7 @@ export interface TokenBalance {
   chainBalances: Array<{
     chainId: SupportedChainId
     balance: bigint
-    tokenAddress: Address
+    tokenAddress: Address | 'native'
     formattedBalance: string
   }>
 }

package/src/types/index.ts

@@ -2,4 +2,6 @@ export * from '@/types/actions.js'
 export * from '@/types/asset.js'
 export * from '@/types/chain.js'
 export * from '@/types/lend/index.js'
+export * from '@/types/swap/index.js'
+export * from '@/types/transaction.js'
 export * from '@/types/wallet.js'

package/src/types/lend/base.ts

@@ -1,7 +1,9 @@
-import type { Address, Hex } from 'viem'
+import type { Address } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
 import type { Asset } from '@/types/asset.js'
+// Import and re-export shared transaction type for backwards compatibility
+import type { TransactionData } from '@/types/transaction.js'
 import type {
   BatchTransactionReturnType,
   TransactionReturnType,
@@ -10,6 +12,7 @@ import type {
 export { LendProvider } from '@/lend/core/LendProvider.js'
 export { ActionsLendNamespace } from '@/lend/namespaces/ActionsLendNamespace.js'
 export { WalletLendNamespace } from '@/lend/namespaces/WalletLendNamespace.js'
+export type { TransactionData }
 
 /**
  * Lending market identifier
@@ -45,19 +48,6 @@ export type LendMarketConfig = LendMarketId & LendMarketConfigMetadata
  */
 export type GetLendMarketParams = LendMarketId
 
-/**
- * Transaction data for execution
- * @description Raw transaction data for wallet execution
- */
-export interface TransactionData {
-  /** Target contract address */
-  to: Address
-  /** Encoded function call data */
-  data: Hex
-  /** ETH value to send */
-  value: bigint
-}
-
 /**
  * Supply metrics for a lending market
  * @description Total assets and shares in the vault
@@ -83,16 +73,13 @@ export interface LendTransaction {
   marketId: string
   /** Estimated APY at time of lending */
   apy: number
-  /** Transaction data for execution (optional) */
-  transactionData?: {
+  /** Transaction data for execution */
+  transactionData: {
     /** Approval transaction (if needed) */
     approval?: TransactionData
-    /** Main operation transaction (openPosition or closePosition) */
-    openPosition?: TransactionData
-    closePosition?: TransactionData
+    /** Main position transaction */
+    position: TransactionData
   }
-  /** Slippage tolerance used */
-  slippage?: number
 }
 
 /**
@@ -204,8 +191,6 @@ export interface LendMarket {
  * @description Configuration options for lending operations
  */
 export interface LendOptions {
-  /** Maximum slippage tolerance (basis points) */
-  slippage?: number
   /** Deadline for transaction (timestamp) */
   deadline?: number
   /** Gas limit override */
@@ -268,8 +253,10 @@ export interface LendOpenPositionParams extends LendOpenPositionBaseParams {
 /**
  * Internal parameters for provider _openPosition method with amount already converted to wei
  */
-export interface LendOpenPositionInternalParams
-  extends Omit<LendOpenPositionBaseParams, 'walletAddress'> {
+export interface LendOpenPositionInternalParams extends Omit<
+  LendOpenPositionBaseParams,
+  'walletAddress'
+> {
   /** Amount to lend in wei */
   amountWei: bigint
   /** Wallet address for receiving shares and as owner (required in internal params) */

package/src/types/lend/contracts.ts

@@ -0,0 +1,18 @@
+import type { Address } from 'viem'
+
+/**
+ * Morpho contract addresses needed per chain
+ */
+export interface MorphoContracts {
+  /** Morpho Blue core contract - market state, positions, supply/withdraw */
+  morphoBlue: Address
+  /** Interest Rate Model contract - borrow rate calculation for APY */
+  irm: Address
+  /** MetaMorpho vault factory (optional, only for vault creation) */
+  metaMorphoFactory?: Address
+}
+
+/**
+ * Registry mapping chainId to Morpho contracts
+ */
+export type MorphoContractsRegistry = Record<number, MorphoContracts>

package/src/types/lend/index.ts

@@ -1,2 +1,3 @@
 export * from '@/types/lend/base.js'
+export * from '@/types/lend/contracts.js'
 export * from '@/types/lend/morpho.js'

package/src/types/swap/base.ts

@@ -0,0 +1,259 @@
+import type { Address } from 'viem'
+
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { SwapProvider } from '@/swap/core/SwapProvider.js'
+import type { Asset } from '@/types/asset.js'
+import type { TransactionData } from '@/types/transaction.js'
+import type {
+  BatchTransactionReturnType,
+  TransactionReturnType,
+} from '@/wallet/core/wallets/abstract/types/index.js'
+
+export { SwapProvider } from '@/swap/core/SwapProvider.js'
+export { ActionsSwapNamespace } from '@/swap/namespaces/ActionsSwapNamespace.js'
+export { WalletSwapNamespace } from '@/swap/namespaces/WalletSwapNamespace.js'
+
+/**
+ * Map of available swap providers keyed by provider name
+ */
+export type SwapProviders = {
+  uniswap?: SwapProvider<SwapProviderConfig>
+}
+
+/**
+ * Swap provider configuration
+ * @description Configuration for a single swap provider (mirrors LendProviderConfig pattern)
+ */
+export interface SwapProviderConfig {
+  /** Default slippage tolerance (e.g., 0.005 for 0.5%) */
+  defaultSlippage?: number
+  /** Maximum allowed slippage (e.g., 0.5 for 50%). Defaults to 0.5. */
+  maxSlippage?: number
+  /** Allowlist of swap markets (optional - defaults to all supported assets) */
+  marketAllowlist?: SwapMarketConfig[]
+  /** Blocklist of swap markets to exclude */
+  marketBlocklist?: SwapMarketConfig[]
+}
+
+/**
+ * Swap market filter
+ * @description Define allowed/blocked trading markets by assets.
+ * 2 assets = one explicit pair. 3+ = all pairs between them.
+ */
+export interface SwapMarketConfig {
+  /** 2 assets = one explicit pair. 3+ = all pairs between them. */
+  assets: [Asset, Asset, ...Asset[]]
+  /** Restrict to a specific chain. Omit = all configured chains. */
+  chainId?: SupportedChainId
+}
+
+/**
+ * Swap market identifier
+ * @description Unique identifier for a swap market (mirrors LendMarketId pattern)
+ */
+export type SwapMarketId = {
+  /** Pool identifier (keccak256 hash of PoolKey) */
+  poolId: string
+  /** Chain ID where this market exists */
+  chainId: SupportedChainId
+}
+
+/**
+ * Parameters for getting a specific swap market
+ */
+export type GetSwapMarketParams = SwapMarketId
+
+/**
+ * Parameters for getting swap markets
+ */
+export interface GetSwapMarketsParams {
+  /** Filter by chain ID */
+  chainId?: SupportedChainId
+  /** Filter by asset (returns markets containing this asset) */
+  asset?: Asset
+}
+
+/**
+ * Parameters for a wallet swap — what the developer passes.
+ * Exactly one of amountIn or amountOut must be provided.
+ */
+export interface WalletSwapParams {
+  /** Amount of input token (human-readable). For exact-in swaps. Mutually exclusive with amountOut. */
+  amountIn?: number
+  /** Amount of output token (human-readable). For exact-out swaps. Mutually exclusive with amountIn. */
+  amountOut?: number
+  /** Token to sell */
+  assetIn: Asset
+  /** Token to buy */
+  assetOut: Asset
+  /** Chain to execute swap on */
+  chainId: SupportedChainId
+  /** Slippage tolerance override (e.g., 0.01 for 1%). Overrides provider and config defaults. */
+  slippage?: number
+  /** Transaction deadline as Unix timestamp. Defaults to now + 1 minute. */
+  deadline?: number
+  /** Recipient address. Defaults to wallet address. */
+  recipient?: Address
+}
+
+/**
+ * Full swap execute parameters including wallet address.
+ * walletAddress is auto-injected by the wallet namespace.
+ */
+export interface SwapExecuteParams extends WalletSwapParams {
+  walletAddress: Address
+}
+
+/**
+ * Fully resolved swap parameters with defaults applied and amounts in wei.
+ * Passed to provider _execute() implementations.
+ */
+export interface ResolvedSwapParams {
+  amountInWei?: bigint
+  amountOutWei?: bigint
+  assetIn: Asset
+  assetOut: Asset
+  slippage: number
+  deadline: number
+  recipient: Address
+  walletAddress: Address
+  chainId: SupportedChainId
+}
+
+/**
+ * Parameters for getting a swap price quote
+ * @description Specify either amountIn (for exact-in) or amountOut (for exact-out),
+ * not both. Amounts should be human-readable numbers (e.g., 100 for 100 USDC).
+ */
+export interface SwapPriceParams {
+  /** Token to get price for (required) */
+  assetIn: Asset
+  /** Token to price against. Defaults to USDC if not provided. */
+  assetOut?: Asset
+  /** Amount of input token (human-readable). Defaults to 1 unit. For exact-in quotes. */
+  amountIn?: number
+  /** Amount of output token (human-readable). For exact-out quotes. */
+  amountOut?: number
+  /** Chain to get price on */
+  chainId: SupportedChainId
+}
+
+/**
+ * Market information for a swap hop
+ */
+export interface SwapMarketInfo {
+  /** Market address or identifier */
+  address: Address
+  /** Fee tier in pips */
+  fee: number
+  /** Protocol version used (v2, v3, v4) */
+  version: 'v2' | 'v3' | 'v4'
+}
+
+/**
+ * Swap route information
+ */
+export interface SwapRoute {
+  /** Ordered list of assets in the route path */
+  path: Asset[]
+  /** Market information for each hop */
+  pools: SwapMarketInfo[]
+}
+
+/**
+ * Swap price quote response
+ */
+export interface SwapPrice {
+  /** Exchange rate as human-readable string (e.g., "3245.50") */
+  price: string
+  /** Inverse exchange rate */
+  priceInverse: string
+  /** Human-readable input amount */
+  amountIn: number
+  /** Human-readable output amount */
+  amountOut: number
+  /** Input amount in wei */
+  amountInWei: bigint
+  /** Expected output amount in wei */
+  amountOutWei: bigint
+  /** Price impact as decimal (0.03 = 3%). Derived from pool mid-price vs execution price. */
+  priceImpact: number
+  /** Route taken for the swap */
+  route: SwapRoute
+  /** Estimated gas cost in wei */
+  gasEstimate?: bigint
+}
+
+/**
+ * Transaction data for swap execution
+ */
+export interface SwapTransactionData {
+  /** Permit2 approval transaction (if needed) */
+  permit2Approval?: TransactionData
+  /** Token approval to Permit2 (if needed) */
+  tokenApproval?: TransactionData
+  /** Main swap transaction */
+  swap: TransactionData
+}
+
+/**
+ * Swap transaction result
+ */
+export interface SwapTransaction {
+  /** Human-readable input amount */
+  amountIn: number
+  /** Human-readable output amount */
+  amountOut: number
+  /** Input amount in wei */
+  amountInWei: bigint
+  /** Output amount in wei (expected) */
+  amountOutWei: bigint
+  /** Input asset */
+  assetIn: Asset
+  /** Output asset */
+  assetOut: Asset
+  /** Execution price */
+  price: string
+  /** Price impact as decimal (0.03 = 3%) */
+  priceImpact: number
+  /** Transaction data for execution */
+  transactionData: SwapTransactionData
+}
+
+/**
+ * Swap execution receipt
+ */
+export interface SwapReceipt {
+  /** Transaction receipt(s) */
+  receipt: TransactionReturnType | BatchTransactionReturnType
+  /** Human-readable input amount */
+  amountIn: number
+  /** Human-readable output amount */
+  amountOut: number
+  /** Actual input amount in wei */
+  amountInWei: bigint
+  /** Actual output amount in wei */
+  amountOutWei: bigint
+  /** Input asset */
+  assetIn: Asset
+  /** Output asset */
+  assetOut: Asset
+  /** Execution price as human-readable string */
+  price: string
+  /** Price impact as decimal (0.03 = 3%) */
+  priceImpact: number
+}
+
+/**
+ * Swap market information
+ */
+export interface SwapMarket {
+  /** Market identifier (contains poolId and chainId) */
+  marketId: SwapMarketId
+  /** Token pair in the market */
+  assets: [Asset, Asset]
+  /** Fee tier in pips (500 = 0.05%) */
+  fee: number
+  /** Provider name */
+  provider: 'uniswap'
+}

package/src/types/swap/index.ts

@@ -0,0 +1 @@
+export * from '@/types/swap/base.js'

package/src/types/transaction.ts

@@ -0,0 +1,14 @@
+import type { Address, Hex } from 'viem'
+
+/**
+ * Transaction data for execution
+ * @description Raw transaction data for wallet execution
+ */
+export interface TransactionData {
+  /** Target contract address */
+  to: Address
+  /** Encoded function call data */
+  data: Hex
+  /** ETH value to send */
+  value: bigint
+}

package/src/utils/assets.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 
-import { MockUSDCAsset, MockWETHAsset } from '@/test/MockAssets.js'
-import { isAssetSupportedOnChain } from '@/utils/assets.js'
+import { MockUSDCAsset, MockWETHAsset } from '@/__mocks__/MockAssets.js'
+import { isAssetSupportedOnChain, parseAssetAmount } from '@/utils/assets.js'
 
 describe('Asset Utilities', () => {
   describe('isAssetSupportedOnChain', () => {
@@ -25,4 +25,19 @@ describe('Asset Utilities', () => {
       expect(MockWETHAsset.type).toBe('erc20')
     })
   })
+
+  describe('parseAssetAmount', () => {
+    it('converts human-readable amount to wei using asset decimals', () => {
+      expect(parseAssetAmount(MockUSDCAsset, 100)).toBe(100000000n)
+      expect(parseAssetAmount(MockWETHAsset, 1)).toBe(1000000000000000000n)
+    })
+
+    it('returns undefined when amount is undefined', () => {
+      expect(parseAssetAmount(MockUSDCAsset, undefined)).toBeUndefined()
+    })
+
+    it('handles fractional amounts', () => {
+      expect(parseAssetAmount(MockUSDCAsset, 0.5)).toBe(500000n)
+    })
+  })
 })

package/src/utils/assets.ts

@@ -5,17 +5,20 @@ import type { SupportedChainId } from '@/constants/supportedChains.js'
 import type { Asset } from '@/types/asset.js'
 
 /**
- * Parse human-readable amount to wei/smallest unit
- * @param amount - Human-readable amount (e.g. 1.5)
- * @param decimals - Token decimals
- * @returns Amount in smallest unit (wei equivalent)
+ * Parse human-readable amount to wei using an asset's decimals.
+ * Returns undefined when amount is undefined.
  */
-export function parseAssetAmount(amount: number, decimals: number): bigint {
-  // Convert number to string with proper precision
-  const amountStr = amount.toString()
-
-  // Use viem's parseUnits for proper decimal handling
-  return parseUnits(amountStr, decimals)
+export function parseAssetAmount(asset: Asset, amount: number): bigint
+export function parseAssetAmount(
+  asset: Asset,
+  amount: number | undefined,
+): bigint | undefined
+export function parseAssetAmount(
+  asset: Asset,
+  amount: number | undefined,
+): bigint | undefined {
+  if (amount === undefined) return undefined
+  return parseUnits(amount.toString(), asset.metadata.decimals)
 }
 
 /**
@@ -37,6 +40,15 @@ export function formatAssetAmount(amount: bigint, decimals: number): number {
   return parseFloat(result)
 }
 
+/**
+ * Check if asset is a native asset (e.g. ETH)
+ * @param asset - Asset definition
+ * @returns Whether the asset is native
+ */
+export function isNativeAsset(asset: Asset): boolean {
+  return asset.type === 'native'
+}
+
 /**
  * Check if asset is supported on a specific chain
  * @param asset - Asset definition
@@ -55,7 +67,7 @@ export function isAssetSupportedOnChain(
  * @param asset - Asset definition
  * @param chainId - Chain ID
  * @returns Asset address on the specified chain
- * @throws Error if asset is not supported on the chain
+ * @throws Error if asset is not supported on the chain or is a native asset
  */
 export function getAssetAddress(
   asset: Asset,
@@ -67,5 +79,10 @@ export function getAssetAddress(
       `Asset ${asset.metadata.symbol} is not supported on chain ${chainId}`,
     )
   }
+  if (address === 'native') {
+    throw new Error(
+      `Asset ${asset.metadata.symbol} is a native asset and has no contract address.`,
+    )
+  }
   return address
 }

package/src/utils/constants.ts

@@ -0,0 +1,4 @@
+/**
+ * Seconds per year for APY calculations (365 days)
+ */
+export const SECONDS_PER_YEAR = 31536000n