@eth-optimism/actions-sdk 0.3.0 → 0.5.0

package/src/swap/providers/velodrome/markets.ts

@@ -0,0 +1,100 @@
+import type { Address } from 'viem'
+import { concat, keccak256 } from 'viem'
+
+import { VELODROME } from '@/constants/providers.js'
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { assetPairs } from '@/swap/core/markets.js'
+import type { Asset } from '@/types/asset.js'
+import type { SwapMarket } from '@/types/swap/index.js'
+
+import type { ResolvedPoolConfig, VelodromeMarketConfig } from './types.js'
+
+/**
+ * Resolve a VelodromeMarketConfig to a discriminated ResolvedPoolConfig.
+ * Exactly one of stable or tickSpacing must be set.
+ * @param config - Raw market config
+ * @returns Resolved pool config with discriminated type
+ * @throws If both or neither of stable/tickSpacing are set
+ */
+export function resolvePoolConfig(
+  config: VelodromeMarketConfig,
+): ResolvedPoolConfig {
+  const hasStable = config.stable !== undefined
+  const hasTick = config.tickSpacing !== undefined
+  if (hasStable && hasTick) {
+    throw new Error(
+      'stable and tickSpacing are mutually exclusive — set one, not both',
+    )
+  }
+  if (!hasStable && !hasTick) {
+    throw new Error(
+      'Either stable (v2 AMM) or tickSpacing (CL) must be configured',
+    )
+  }
+  if (hasTick) {
+    return { type: 'cl', tickSpacing: config.tickSpacing! }
+  }
+  return { type: 'v2', stable: config.stable! }
+}
+
+/**
+ * Expand a single VelodromeMarketConfig into SwapMarket objects for a given chain.
+ * Used as the `toMarkets` callback for shared findMarket/expandMarkets.
+ * @param config - Market config with pool parameters
+ * @param chainId - Target chain
+ * @param asset - If provided, only return markets containing this asset
+ */
+export function configToMarkets(
+  config: VelodromeMarketConfig,
+  chainId: SupportedChainId,
+  asset?: Asset,
+): SwapMarket[] {
+  const poolConfig = resolvePoolConfig(config)
+  return assetPairs(config.assets, asset)
+    .map(([a, b]) => pairToMarket(a, b, chainId, poolConfig))
+    .filter((m): m is SwapMarket => m !== null)
+}
+
+/**
+ * Build a SwapMarket from two assets and Velodrome pool parameters.
+ * For v2: poolId = keccak256(sortedA, sortedB, stable)
+ * For CL: poolId = keccak256(sortedA, sortedB, tickSpacing as int24)
+ * @returns SwapMarket, or null if either asset lacks an address on this chain
+ */
+function pairToMarket(
+  assetA: Asset,
+  assetB: Asset,
+  chainId: SupportedChainId,
+  poolConfig: ResolvedPoolConfig,
+): SwapMarket | null {
+  const addrA = assetA.address[chainId]
+  const addrB = assetB.address[chainId]
+  if (!addrA || addrA === 'native' || !addrB || addrB === 'native') return null
+
+  const [sortedA, sortedB] =
+    addrA.toLowerCase() < addrB.toLowerCase() ? [addrA, addrB] : [addrB, addrA]
+
+  let poolId: string
+  if (poolConfig.type === 'cl') {
+    const tickBytes =
+      `0x${(poolConfig.tickSpacing & 0xffffff).toString(16).padStart(6, '0')}` as `0x${string}`
+    poolId = keccak256(
+      concat([sortedA as Address, sortedB as Address, tickBytes]),
+    )
+  } else {
+    poolId = keccak256(
+      concat([
+        sortedA as Address,
+        sortedB as Address,
+        poolConfig.stable ? '0x01' : '0x00',
+      ]),
+    )
+  }
+
+  return {
+    marketId: { poolId, chainId },
+    assets: [assetA, assetB],
+    fee: 0,
+    provider: VELODROME,
+  }
+}

package/src/swap/providers/velodrome/types.ts

@@ -0,0 +1,30 @@
+import type {
+  SwapMarketConfig,
+  SwapProviderConfig,
+} from '@/types/swap/index.js'
+
+/**
+ * Velodrome/Aerodrome market config.
+ * Exactly one of `stable` (v2 AMM) or `tickSpacing` (CL/Slipstream) must be set.
+ */
+export interface VelodromeMarketConfig extends SwapMarketConfig {
+  /** true = stable pool (correlated assets), false = volatile pool. For v2 AMM pools. */
+  stable?: boolean
+  /** Tick spacing for CL/Slipstream pools. Mutually exclusive with stable. */
+  tickSpacing?: number
+}
+
+/** Resolved v2 AMM pool config */
+export type ResolvedV2Config = { type: 'v2'; stable: boolean }
+/** Resolved CL/Slipstream pool config */
+export type ResolvedCLConfig = { type: 'cl'; tickSpacing: number }
+/** Discriminated union of resolved pool configs */
+export type ResolvedPoolConfig = ResolvedV2Config | ResolvedCLConfig
+
+/**
+ * Velodrome/Aerodrome swap provider configuration
+ */
+export interface VelodromeSwapProviderConfig extends SwapProviderConfig {
+  marketAllowlist?: VelodromeMarketConfig[]
+  marketBlocklist?: VelodromeMarketConfig[]
+}

package/src/types/actions.ts

@@ -1,12 +1,16 @@
 import type { UniswapSwapProviderConfig } from '@/swap/providers/uniswap/types.js'
+import type { VelodromeSwapProviderConfig } from '@/swap/providers/velodrome/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 { LendProviders, SwapProviders } from '@/types/providers.js'
 import type { SwapProviderConfig } from '@/types/swap/index.js'
 import type { ProviderSpec } from '@/wallet/core/providers/hosted/types/index.js'
 
 // Re-export provider configs for convenience
 export type { LendProviderConfig, SwapProviderConfig }
+// Re-export centralized provider maps
+export type { LendProviders, SwapProviders } from '@/types/providers.js'
 
 /** Require at least one property to be defined */
 type RequireAtLeastOne<T> = {
@@ -17,19 +21,54 @@ type RequireAtLeastOne<T> = {
  * Lending configuration — at least one provider must be configured
  */
 export type LendConfig = RequireAtLeastOne<{
-  /** Morpho lending provider configuration */
-  morpho?: LendProviderConfig
-  /** Aave lending provider configuration */
-  aave?: LendProviderConfig
+  [K in keyof LendProviders]: LendProviderConfig
 }>
 
+/** Names of available swap providers — derived from SwapProviders registry */
+export type SwapProviderName = keyof SwapProviders
+
+/** Names of available lend providers — derived from LendProviders registry */
+export type LendProviderName = keyof LendProviders
+
+/** Routing strategy for selecting a provider when multiple are configured. */
+export type SwapRoutingStrategy = 'price'
+
 /**
- * Swap configuration — at least one provider must be configured
+ * Shared swap settings applied across all providers.
+ * Provider-level values override these when set.
+ */
+export interface SwapSettings {
+  /** Default slippage tolerance (e.g., 0.005 for 0.5%). Defaults to 0.005. */
+  defaultSlippage?: number
+  /** Maximum allowed slippage (e.g., 0.5 for 50%). Defaults to 0.5. */
+  maxSlippage?: number
+  /** Quote expiration in seconds from now. Defaults to 60. */
+  quoteExpirationSeconds?: number
+  /** Permit2 sub-approval expiration in seconds from now. Defaults to 2592000 (30 days). */
+  permit2ExpirationSeconds?: number
+  /**
+   * Routing strategy for multi-provider selection.
+   * 'price' fetches quotes from all eligible providers and returns the best price.
+   * Omit to fall back to market-matching heuristics.
+   */
+  routing?: SwapRoutingStrategy
+  /** Provider to prefer when routing produces a tie, or to always use when no routing strategy is set. */
+  defaultProvider?: SwapProviderName
+}
+
+/**
+ * Swap configuration — at least one provider must be configured.
+ * Shared settings go in `config`; per-provider settings go under the provider key.
  */
 export type SwapConfig = RequireAtLeastOne<{
   /** Uniswap swap provider configuration */
   uniswap?: UniswapSwapProviderConfig
-}>
+  /** Velodrome/Aerodrome swap provider configuration */
+  velodrome?: VelodromeSwapProviderConfig
+}> & {
+  /** Shared settings applied across all providers */
+  settings?: SwapSettings
+}
 
 /**
  * Network configuration for lending providers
@@ -42,12 +81,13 @@ export interface LendNetworkConfig {
 
 /**
  * Assets configuration
- * @description Configuration for supported assets
+ * @description Configuration for supported assets. Import token constants from the SDK
+ * or define your own Asset objects.
  */
 export interface AssetsConfig {
-  /** Allowlist of assets to support (optional - defaults to all SUPPORTED_TOKENS) */
+  /** Allowlist of assets to support. No default — developers must explicitly configure. */
   allow?: Asset[]
-  /** Blocklist of assets to exclude (optional) */
+  /** Blocklist of assets to exclude from the allow list. Only effective when allow is also set. For future use with runtime asset fetching. */
   block?: Asset[]
 }
 

package/src/types/asset.ts

@@ -22,13 +22,16 @@ export interface Asset {
  * Detailed token balance information
  */
 export interface TokenBalance {
-  symbol: string
-  totalBalance: bigint
-  totalFormattedBalance: string
-  chainBalances: Array<{
-    chainId: SupportedChainId
-    balance: bigint
-    tokenAddress: Address | 'native'
-    formattedBalance: string
-  }>
+  asset: Asset
+  totalBalance: number
+  totalBalanceRaw: bigint
+  chains: Partial<
+    Record<
+      SupportedChainId,
+      {
+        balance: number
+        balanceRaw: bigint
+      }
+    >
+  >
 }

package/src/types/chain.ts

@@ -1,4 +1,4 @@
-import type { SUPPORTED_CHAIN_IDS } from '@/constants/supportedChains.js'
+import type { SupportedChainId } from '@/constants/supportedChains.js'
 
 /**
  * Chain configuration
@@ -6,7 +6,7 @@ import type { SUPPORTED_CHAIN_IDS } from '@/constants/supportedChains.js'
  */
 export interface ChainConfig {
   /** Chain ID */
-  chainId: (typeof SUPPORTED_CHAIN_IDS)[number]
+  chainId: SupportedChainId
   /** RPC URL for the chain */
   rpcUrls?: string[]
   /** Bundler configuration */

package/src/types/lend/base.ts

@@ -1,6 +1,7 @@
 import type { Address } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
+import type { LendProviderName } from '@/types/actions.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'
@@ -33,7 +34,7 @@ export type LendMarketConfigMetadata = {
   /** Asset information for this market */
   asset: Asset
   /** Lending provider type */
-  lendProvider: 'morpho' | 'aave'
+  lendProvider: LendProviderName
 }
 
 /**
@@ -135,7 +136,8 @@ export interface LendMarketInfo extends LendMarketBase {
 
 /**
  * APY breakdown for detailed display
- * @description Breakdown of APY components following Morpho's official methodology
+ * @description Breakdown of APY components following Morpho's official methodology.
+ * Individual token reward APRs are keyed by lowercase token address.
  */
 export interface ApyBreakdown {
   /** Total net APY after all components and fees */
@@ -144,12 +146,10 @@ export interface ApyBreakdown {
   native: number
   /** Total rewards APR from all sources */
   totalRewards: number
-  /** Individual token rewards APRs (dynamically populated) */
-  usdc?: number
-  morpho?: number
-  other?: number
   /** Performance/management fee rate */
   performanceFee: number
+  /** Individual token reward APRs keyed by address, plus 'other' for unrecognized */
+  [key: string]: number | undefined
 }
 
 /**

package/src/types/lend/contracts.ts

@@ -1,5 +1,7 @@
 import type { Address } from 'viem'
 
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+
 /**
  * Morpho contract addresses needed per chain
  */
@@ -15,4 +17,6 @@ export interface MorphoContracts {
 /**
  * Registry mapping chainId to Morpho contracts
  */
-export type MorphoContractsRegistry = Record<number, MorphoContracts>
+export type MorphoContractsRegistry = Partial<
+  Record<SupportedChainId, MorphoContracts>
+>

package/src/types/providers.ts

@@ -0,0 +1,22 @@
+import type { LendProvider } from '@/lend/core/LendProvider.js'
+import type { SwapProvider } from '@/swap/core/SwapProvider.js'
+import type { LendProviderConfig } from '@/types/lend/index.js'
+import type { SwapProviderConfig } from '@/types/swap/index.js'
+
+/**
+ * Map of available lend providers keyed by provider name.
+ * Add new lend providers here — this is the single source of truth.
+ */
+export type LendProviders = {
+  morpho?: LendProvider<LendProviderConfig>
+  aave?: LendProvider<LendProviderConfig>
+}
+
+/**
+ * Map of available swap providers keyed by provider name.
+ * Add new swap providers here — this is the single source of truth.
+ */
+export type SwapProviders = {
+  uniswap?: SwapProvider<SwapProviderConfig>
+  velodrome?: SwapProvider<SwapProviderConfig>
+}

package/src/types/swap/base.ts

@@ -1,7 +1,8 @@
-import type { Address } from 'viem'
+import type { Address, Hex } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import type { SwapProvider } from '@/swap/core/SwapProvider.js'
+import type { EnsName } from '@/ens/types.js'
+import type { SwapProviderName } from '@/types/actions.js'
 import type { Asset } from '@/types/asset.js'
 import type { TransactionData } from '@/types/transaction.js'
 import type {
@@ -12,23 +13,19 @@ import type {
 export { SwapProvider } from '@/swap/core/SwapProvider.js'
 export { ActionsSwapNamespace } from '@/swap/namespaces/ActionsSwapNamespace.js'
 export { WalletSwapNamespace } from '@/swap/namespaces/WalletSwapNamespace.js'
+export type { SwapProviders } from '@/types/providers.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)
+ * Per-provider swap configuration.
+ * Provider-level values override the shared SwapGlobalConfig defaults.
  */
 export interface SwapProviderConfig {
-  /** Default slippage tolerance (e.g., 0.005 for 0.5%) */
+  /** Slippage tolerance override for this provider (e.g., 0.005 for 0.5%) */
   defaultSlippage?: number
-  /** Maximum allowed slippage (e.g., 0.5 for 50%). Defaults to 0.5. */
+  /** Maximum allowed slippage override for this provider (e.g., 0.5 for 50%) */
   maxSlippage?: number
+  /** Quote expiration override for this provider, in seconds from now */
+  quoteExpirationSeconds?: number
   /** Allowlist of swap markets (optional - defaults to all supported assets) */
   marketAllowlist?: SwapMarketConfig[]
   /** Blocklist of swap markets to exclude */
@@ -92,8 +89,10 @@ export interface WalletSwapParams {
   slippage?: number
   /** Transaction deadline as Unix timestamp. Defaults to now + 1 minute. */
   deadline?: number
-  /** Recipient address. Defaults to wallet address. */
-  recipient?: Address
+  /** Recipient address or ENS name (e.g. "vitalik.eth"). Defaults to wallet address. */
+  recipient?: Address | EnsName
+  /** Explicitly select a swap provider. Overrides routing config. */
+  provider?: SwapProviderName
 }
 
 /**
@@ -105,12 +104,12 @@ export interface SwapExecuteParams extends WalletSwapParams {
 }
 
 /**
- * Fully resolved swap parameters with defaults applied and amounts in wei.
+ * Fully resolved swap parameters with defaults applied and amounts as raw bigint.
  * Passed to provider _execute() implementations.
  */
 export interface ResolvedSwapParams {
-  amountInWei?: bigint
-  amountOutWei?: bigint
+  amountInRaw?: bigint
+  amountOutRaw?: bigint
   assetIn: Asset
   assetOut: Asset
   slippage: number
@@ -136,6 +135,121 @@ export interface SwapPriceParams {
   amountOut?: number
   /** Chain to get price on */
   chainId: SupportedChainId
+  /** Explicitly select a swap provider. Overrides routing config. */
+  provider?: SwapProviderName
+}
+
+/**
+ * Parameters for getting a swap quote with pre-built execution data.
+ */
+export interface SwapQuoteParams {
+  /** Token to sell */
+  assetIn: Asset
+  /** Token to buy (required) */
+  assetOut: Asset
+  /** Amount of input token (human-readable). Mutually exclusive with amountOut. */
+  amountIn?: number
+  /** Amount of output token (human-readable). Mutually exclusive with amountIn. */
+  amountOut?: number
+  /** Chain to execute swap on */
+  chainId: SupportedChainId
+  /** Slippage tolerance baked into the quote */
+  slippage?: number
+  /** Transaction deadline as Unix timestamp */
+  deadline?: number
+  /** Recipient address or ENS name (e.g. "vitalik.eth"). Defaults to wallet address. */
+  recipient?: Address | EnsName
+  /** Explicitly select a swap provider */
+  provider?: SwapProviderName
+}
+
+/**
+ * Pre-built execution data from a quote, ready to submit on-chain.
+ */
+export interface SwapQuoteExecution {
+  /** Encoded swap calldata */
+  swapCalldata: Hex
+  /** Router/contract to send the swap transaction to */
+  routerAddress: Address
+  /** Native ETH value for ETH-in swaps, else 0n */
+  value: bigint
+  /** Opaque provider-specific context (e.g. stable flag, factory address) */
+  providerContext?: Record<string, unknown>
+}
+
+/**
+ * A complete swap quote: pricing, amounts, and pre-built execution data.
+ * Pass to execute() to skip re-quoting.
+ *
+ * **Precision note:** `Raw` fields (bigint) are the on-chain source of truth.
+ * Number fields (`amountIn`, `amountOut`, `price`, etc.) are display approximations
+ * derived via `formatUnits` → `parseFloat`. For tokens with many significant digits,
+ * numbers may lose precision. Use `Raw` fields for any math that matters.
+ */
+export interface SwapQuote {
+  // ── What you're swapping ──
+  /** Token being sold */
+  assetIn: Asset
+  /** Token being bought */
+  assetOut: Asset
+  /** Chain to execute on */
+  chainId: SupportedChainId
+
+  // ── Amounts (Raw = on-chain precision, number = display approximation) ──
+  /** Human-readable input amount (display only — use amountInRaw for precision) */
+  amountIn: number
+  /** Input amount as raw bigint (native decimals). Source of truth. */
+  amountInRaw: bigint
+  /** Human-readable expected output (display only — use amountOutRaw for precision) */
+  amountOut: number
+  /** Expected output as raw bigint. Source of truth. */
+  amountOutRaw: bigint
+  /** Human-readable minimum output after slippage (display only) */
+  amountOutMin: number
+  /** Minimum output as raw bigint after slippage. Source of truth for on-chain execution. */
+  amountOutMinRaw: bigint
+
+  // ── Price (display approximations derived from number amounts) ──
+  /** Exchange rate: amountOut / amountIn. Display approximation. */
+  price: number
+  /** Inverse exchange rate: amountIn / amountOut. Display approximation. */
+  priceInverse: number
+  /** Price impact as decimal (0.03 = 3%) */
+  priceImpact: number
+
+  // ── Route ──
+  /** Route taken for the swap */
+  route: SwapRoute
+
+  // ── Execution ──
+  /** Pre-built transaction data. Pass quote to execute() to use. */
+  execution: SwapQuoteExecution
+
+  // ── Metadata ──
+  /** Provider that generated this quote */
+  provider: SwapProviderName
+  /** Slippage tolerance applied to this quote */
+  slippage: number
+  /** Transaction deadline (Unix seconds) */
+  deadline: number
+  /** When the quote was generated (Unix seconds) */
+  quotedAt: number
+  /** When the quote expires (Unix seconds) */
+  expiresAt: number
+  /** Estimated gas cost as raw bigint (native decimals) */
+  gasEstimate?: bigint
+  /**
+   * Wallet address that will execute this quote.
+   * Set by WalletSwapNamespace before execution — not available on price-only quotes.
+   * Used to check existing on-chain allowances and skip redundant approvals.
+   */
+  recipient?: Address
+  /**
+   * The recipient address baked into execution.swapCalldata at quote time.
+   * If recipient differs from quotedRecipient at execute time, calldata is re-encoded
+   * with the correct recipient to prevent tokens from being sent to the wrong address.
+   */
+  quotedRecipient: Address
 }
 
 /**
@@ -172,15 +286,15 @@ export interface SwapPrice {
   amountIn: number
   /** Human-readable output amount */
   amountOut: number
-  /** Input amount in wei */
-  amountInWei: bigint
-  /** Expected output amount in wei */
-  amountOutWei: bigint
+  /** Input amount as raw bigint (native decimals) */
+  amountInRaw: bigint
+  /** Expected output amount as raw bigint (native decimals) */
+  amountOutRaw: 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 */
+  /** Estimated gas cost as raw bigint (native decimals) */
   gasEstimate?: bigint
 }
 
@@ -204,16 +318,16 @@ export interface SwapTransaction {
   amountIn: number
   /** Human-readable output amount */
   amountOut: number
-  /** Input amount in wei */
-  amountInWei: bigint
-  /** Output amount in wei (expected) */
-  amountOutWei: bigint
+  /** Input amount as raw bigint (native decimals) */
+  amountInRaw: bigint
+  /** Output amount as raw bigint (native decimals) (expected) */
+  amountOutRaw: bigint
   /** Input asset */
   assetIn: Asset
   /** Output asset */
   assetOut: Asset
-  /** Execution price */
-  price: string
+  /** Exchange rate: amountOut / amountIn */
+  price: number
   /** Price impact as decimal (0.03 = 3%) */
   priceImpact: number
   /** Transaction data for execution */
@@ -230,16 +344,16 @@ export interface SwapReceipt {
   amountIn: number
   /** Human-readable output amount */
   amountOut: number
-  /** Actual input amount in wei */
-  amountInWei: bigint
-  /** Actual output amount in wei */
-  amountOutWei: bigint
+  /** Actual input amount as raw bigint (native decimals) */
+  amountInRaw: bigint
+  /** Actual output amount as raw bigint (native decimals) */
+  amountOutRaw: bigint
   /** Input asset */
   assetIn: Asset
   /** Output asset */
   assetOut: Asset
-  /** Execution price as human-readable string */
-  price: string
+  /** Exchange rate: amountOut / amountIn */
+  price: number
   /** Price impact as decimal (0.03 = 3%) */
   priceImpact: number
 }
@@ -255,5 +369,5 @@ export interface SwapMarket {
   /** Fee tier in pips (500 = 0.05%) */
   fee: number
   /** Provider name */
-  provider: 'uniswap'
+  provider: SwapProviderName
 }