@eth-optimism/actions-sdk 0.3.0 → 0.5.0

package/src/constants/providers.ts

@@ -0,0 +1,5 @@
+/** Provider identifiers — must match keys in SwapProviders/LendProviders types */
+export const UNISWAP = 'uniswap' as const
+export const VELODROME = 'velodrome' as const
+export const AAVE = 'aave' as const
+export const MORPHO = 'morpho' as const

package/src/constants/supportedChains.ts

@@ -1,16 +1,26 @@
 import {
   base,
   baseSepolia,
+  bob,
+  celo,
+  fraxtal,
+  ink,
+  lisk,
   mainnet,
+  metalL2,
+  mode,
   optimism,
   optimismSepolia,
   sepolia,
+  soneium,
+  superseed,
+  swellchain,
   unichain,
   unichainSepolia,
   worldchain,
 } from 'viem/chains'
 
-export const SUPPORTED_CHAIN_IDS = [
+export const ACTIONS_SUPPORTED_CHAIN_IDS = [
   mainnet.id,
   sepolia.id,
   optimism.id,
@@ -20,6 +30,16 @@ export const SUPPORTED_CHAIN_IDS = [
   unichain.id,
   unichainSepolia.id,
   worldchain.id,
+  bob.id,
+  celo.id,
+  fraxtal.id,
+  ink.id,
+  lisk.id,
+  metalL2.id,
+  mode.id,
+  soneium.id,
+  superseed.id,
+  swellchain.id,
 ] as const
 
-export type SupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number]
+export type SupportedChainId = (typeof ACTIONS_SUPPORTED_CHAIN_IDS)[number]

package/src/ens/EnsNamespace.spec.ts

@@ -0,0 +1,171 @@
+import type { Address, PublicClient } from 'viem'
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+
+import { EnsNamespace } from './EnsNamespace.js'
+import { EnsResolutionError, EnsRpcError } from './errors.js'
+import type { EnsName } from './types.js'
+
+const REAL_ADDRESS = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' as Address
+const ENS_NAME = 'vitalik.eth' as EnsName
+
+function mockChainManager(client?: Partial<PublicClient>): ChainManager {
+  const tryGetPublicClient = client
+    ? vi.fn().mockReturnValue(client)
+    : vi.fn().mockReturnValue(undefined)
+  return { tryGetPublicClient } as unknown as ChainManager
+}
+
+function mockClient(
+  overrides: Partial<PublicClient> = {},
+): Partial<PublicClient> {
+  return {
+    getEnsAddress: vi.fn().mockResolvedValue(REAL_ADDRESS),
+    getEnsName: vi.fn().mockResolvedValue(ENS_NAME),
+    getEnsText: vi.fn().mockResolvedValue(null),
+    ...overrides,
+  }
+}
+
+describe('EnsNamespace', () => {
+  describe('getAddress', () => {
+    it('resolves a hex address directly', async () => {
+      const ens = new EnsNamespace(mockChainManager())
+      expect(await ens.getAddress(REAL_ADDRESS)).toBe(REAL_ADDRESS)
+    })
+
+    it('resolves an ENS name via mainnet client', async () => {
+      const client = mockClient()
+      const ens = new EnsNamespace(mockChainManager(client))
+      expect(await ens.getAddress(ENS_NAME)).toBe(REAL_ADDRESS)
+      expect(client.getEnsAddress).toHaveBeenCalledWith({ name: ENS_NAME })
+    })
+
+    it('caches resolved addresses on subsequent calls', async () => {
+      const client = mockClient()
+      const ens = new EnsNamespace(mockChainManager(client))
+      await ens.getAddress(ENS_NAME)
+      await ens.getAddress(ENS_NAME)
+      expect(client.getEnsAddress).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('getName', () => {
+    it('returns ENS name for a known address', async () => {
+      const client = mockClient()
+      const ens = new EnsNamespace(mockChainManager(client))
+      expect(await ens.getName(REAL_ADDRESS)).toBe(ENS_NAME)
+      expect(client.getEnsName).toHaveBeenCalledWith({ address: REAL_ADDRESS })
+    })
+
+    it('returns null when no primary name is set', async () => {
+      const client = mockClient({ getEnsName: vi.fn().mockResolvedValue(null) })
+      const ens = new EnsNamespace(mockChainManager(client))
+      expect(await ens.getName(REAL_ADDRESS)).toBeNull()
+    })
+
+    it('throws EnsRpcError on RPC failure', async () => {
+      const client = mockClient({
+        getEnsName: vi.fn().mockRejectedValue(new Error('rpc down')),
+      })
+      const ens = new EnsNamespace(mockChainManager(client))
+      await expect(ens.getName(REAL_ADDRESS)).rejects.toThrow(EnsRpcError)
+    })
+
+    it('caches results on subsequent calls', async () => {
+      const client = mockClient()
+      const ens = new EnsNamespace(mockChainManager(client))
+      await ens.getName(REAL_ADDRESS)
+      await ens.getName(REAL_ADDRESS)
+      expect(client.getEnsName).toHaveBeenCalledTimes(1)
+    })
+
+    it('caches null results', async () => {
+      const client = mockClient({ getEnsName: vi.fn().mockResolvedValue(null) })
+      const ens = new EnsNamespace(mockChainManager(client))
+      await ens.getName(REAL_ADDRESS)
+      await ens.getName(REAL_ADDRESS)
+      expect(client.getEnsName).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('getInfo', () => {
+    it('returns all-null EnsInfo when address has no primary name', async () => {
+      const client = mockClient({ getEnsName: vi.fn().mockResolvedValue(null) })
+      const ens = new EnsNamespace(mockChainManager(client))
+      const info = await ens.getInfo(REAL_ADDRESS)
+      expect(info).toEqual({
+        avatar: null,
+        display: null,
+        description: null,
+        url: null,
+        email: null,
+        keywords: null,
+        twitter: null,
+        github: null,
+        discord: null,
+        reddit: null,
+      })
+    })
+
+    it('returns all text record fields when name is given', async () => {
+      const client = mockClient({
+        getEnsText: vi.fn().mockResolvedValue('test-value'),
+      })
+      const ens = new EnsNamespace(mockChainManager(client))
+      const info = await ens.getInfo(ENS_NAME)
+      expect(info.avatar).toBe('test-value')
+      expect(info.twitter).toBe('test-value')
+      expect(info.github).toBe('test-value')
+    })
+
+    it('returns null fields when text records are not set', async () => {
+      const client = mockClient({ getEnsText: vi.fn().mockResolvedValue(null) })
+      const ens = new EnsNamespace(mockChainManager(client))
+      const info = await ens.getInfo(ENS_NAME)
+      expect(info.avatar).toBeNull()
+      expect(info.twitter).toBeNull()
+    })
+
+    it('fetches all 10 standard keys in parallel', async () => {
+      const client = mockClient({ getEnsText: vi.fn().mockResolvedValue(null) })
+      const ens = new EnsNamespace(mockChainManager(client))
+      await ens.getInfo(ENS_NAME)
+      expect(client.getEnsText).toHaveBeenCalledTimes(10)
+    })
+
+    it('throws EnsRpcError on text lookup RPC failure', async () => {
+      const client = mockClient({
+        getEnsText: vi.fn().mockRejectedValue(new Error('rpc down')),
+      })
+      const ens = new EnsNamespace(mockChainManager(client))
+      await expect(ens.getInfo(ENS_NAME)).rejects.toThrow(EnsRpcError)
+    })
+
+    it('throws EnsResolutionError when the resolved name fails normalization', async () => {
+      const client = mockClient({
+        getEnsName: vi.fn().mockResolvedValue('not!valid.eth'),
+      })
+      const ens = new EnsNamespace(mockChainManager(client))
+      await expect(ens.getInfo(REAL_ADDRESS)).rejects.toThrow(
+        EnsResolutionError,
+      )
+    })
+
+    it('skips reverse resolution when input is already an EnsName', async () => {
+      const client = mockClient({ getEnsText: vi.fn().mockResolvedValue(null) })
+      const ens = new EnsNamespace(mockChainManager(client))
+      await ens.getInfo(ENS_NAME)
+      expect(client.getEnsName).not.toHaveBeenCalled()
+    })
+
+    it('caches results on subsequent calls', async () => {
+      const client = mockClient({ getEnsText: vi.fn().mockResolvedValue(null) })
+      const ens = new EnsNamespace(mockChainManager(client))
+      await ens.getInfo(ENS_NAME)
+      await ens.getInfo(ENS_NAME)
+      expect(client.getEnsText).toHaveBeenCalledTimes(10)
+    })
+  })
+})

package/src/ens/EnsNamespace.ts

@@ -0,0 +1,210 @@
+import { type Address, createPublicClient, http } from 'viem'
+import { mainnet } from 'viem/chains'
+import { normalize } from 'viem/ens'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import { resolveAddress } from '@/utils/ens.js'
+
+import { EnsResolutionError, EnsRpcError } from './errors.js'
+import {
+  type EnsInfo,
+  type EnsName,
+  isEnsName,
+  type NameServiceProvider,
+} from './types.js'
+
+/** Default TTL for cached ENS lookups — 5 minutes */
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000
+
+/** Public mainnet RPC used as fallback when mainnet is not in chain config */
+const FALLBACK_MAINNET_RPC = 'https://cloudflare-eth.com'
+
+/** ENSIP-5 / ENSIP-18 standard text record keys mapped to EnsInfo field names */
+const ENS_TEXT_KEYS = {
+  avatar: 'avatar',
+  display: 'display',
+  description: 'description',
+  url: 'url',
+  email: 'email',
+  keywords: 'keywords',
+  twitter: 'com.twitter',
+  github: 'com.github',
+  discord: 'com.discord',
+  reddit: 'org.reddit',
+} as const satisfies Record<keyof EnsInfo, string>
+
+/**
+ * Namespace for human-readable name resolution on Ethereum.
+ * Currently backed by ENS (Ethereum Name Service) on mainnet.
+ *
+ * Implements {@link NameServiceProvider} — designed to be extensible: future
+ * versions could support alternative name services alongside ENS (e.g. Basename,
+ * Unstoppable Domains, Lens handles). The natural evolution is additional
+ * NameServiceProvider implementations registered under their own namespace
+ * (e.g. `actions.basename`).
+ *
+ * Falls back to a public mainnet RPC automatically if mainnet is not included
+ * in your chain configuration, so ENS works even in L2-only setups.
+ */
+export class EnsNamespace implements NameServiceProvider {
+  private chainManager: ChainManager
+  private readonly cacheTtlMs: number
+  private addressCache = new Map<
+    string,
+    { value: Address; expiresAt: number }
+  >()
+  private nameCache = new Map<
+    Address,
+    { value: EnsName | null; expiresAt: number }
+  >()
+  private infoCache = new Map<string, { value: EnsInfo; expiresAt: number }>()
+
+  constructor(chainManager: ChainManager, cacheTtlMs = DEFAULT_CACHE_TTL_MS) {
+    this.chainManager = chainManager
+    this.cacheTtlMs = cacheTtlMs
+  }
+
+  /**
+   * Resolve an ENS name or hex address to a checksummed hex address.
+   * Hex addresses are returned as-is after format validation.
+   *
+   * If you need to resolve outside of an {@link Actions} instance (e.g. in a
+   * provider or script), use the lower-level `resolveAddress` utility instead.
+   * @param input - Hex address (0x...) or ENS name (e.g. "vitalik.eth")
+   * @returns Resolved hex address
+   * @throws {EnsResolutionError} If the name cannot be resolved
+   * @throws {EnsRpcError} If the RPC call fails
+   */
+  async getAddress(input: Address | EnsName): Promise<Address> {
+    const cached = this.addressCache.get(input)
+    if (cached && Date.now() < cached.expiresAt) return cached.value
+    const value = await resolveAddress(input, this.getMainnetClient())
+    this.addressCache.set(input, {
+      value,
+      expiresAt: Date.now() + this.cacheTtlMs,
+    })
+    return value
+  }
+
+  /**
+   * Reverse-resolve an address to its primary ENS name.
+   * @param address - Hex address to look up
+   * @returns ENS name, or null if none is set
+   * @throws {EnsRpcError} If the RPC call fails
+   */
+  async getName(address: Address): Promise<EnsName | null> {
+    const cached = this.nameCache.get(address)
+    if (cached && Date.now() < cached.expiresAt) return cached.value
+    const name = await this.getMainnetClient()
+      .getEnsName({ address })
+      .catch((cause: unknown) => {
+        throw new EnsRpcError(
+          `ENS reverse resolution failed for "${address}": RPC error`,
+          address,
+          { cause },
+        )
+      })
+    const value = name && isEnsName(name) ? name : null
+    this.nameCache.set(address, {
+      value,
+      expiresAt: Date.now() + this.cacheTtlMs,
+    })
+    return value
+  }
+
+  /**
+   * Fetch all standard ENS profile text record fields (ENSIP-5 / ENSIP-18)
+   * for an ENS name or address in a single batched call.
+   *
+   * All fields are null when not set. Returns all-null if the address has
+   * no primary ENS name.
+   * @param input - Hex address (0x...) or ENS name
+   * @returns EnsInfo object with all standard text record fields
+   * @throws {EnsResolutionError} If the name cannot be normalized
+   * @throws {EnsRpcError} If the RPC call fails
+   */
+  async getInfo(input: Address | EnsName): Promise<EnsInfo> {
+    const name = isEnsName(input) ? input : await this.getName(input)
+    if (!name) return nullInfo()
+
+    const cached = this.infoCache.get(name)
+    if (cached && Date.now() < cached.expiresAt) return cached.value
+
+    const normalized = (() => {
+      try {
+        return normalize(name)
+      } catch (cause) {
+        throw new EnsResolutionError(
+          `ENS name "${name}" is invalid and cannot be normalized`,
+          name,
+          { cause },
+        )
+      }
+    })()
+
+    const client = this.getMainnetClient()
+    const fetchKey = (key: string) =>
+      client.getEnsText({ name: normalized, key }).catch((cause: unknown) => {
+        throw new EnsRpcError(
+          `ENS text record lookup failed for "${name}" key "${key}": RPC error`,
+          name,
+          { cause },
+        )
+      })
+
+    const [
+      avatar,
+      display,
+      description,
+      url,
+      email,
+      keywords,
+      twitter,
+      github,
+      discord,
+      reddit,
+    ] = await Promise.all(Object.values(ENS_TEXT_KEYS).map(fetchKey))
+
+    const value: EnsInfo = {
+      avatar: avatar ?? null,
+      display: display ?? null,
+      description: description ?? null,
+      url: url ?? null,
+      email: email ?? null,
+      keywords: keywords ?? null,
+      twitter: twitter ?? null,
+      github: github ?? null,
+      discord: discord ?? null,
+      reddit: reddit ?? null,
+    }
+
+    this.infoCache.set(name, { value, expiresAt: Date.now() + this.cacheTtlMs })
+    return value
+  }
+
+  private getMainnetClient() {
+    return (
+      this.chainManager.tryGetPublicClient(mainnet.id) ??
+      createPublicClient({
+        chain: mainnet,
+        transport: http(FALLBACK_MAINNET_RPC),
+        batch: { multicall: true },
+      })
+    )
+  }
+}
+
+function nullInfo(): EnsInfo {
+  return {
+    avatar: null,
+    display: null,
+    description: null,
+    url: null,
+    email: null,
+    keywords: null,
+    twitter: null,
+    github: null,
+    discord: null,
+    reddit: null,
+  }
+}

package/src/ens/errors.ts

@@ -0,0 +1,45 @@
+import { mainnet } from 'viem/chains'
+
+/**
+ * Thrown when an ENS operation is attempted but the required chain is not
+ * included in the Actions chain configuration.
+ */
+export class EnsNotConfiguredError extends Error {
+  chainId: number
+
+  constructor(chainId = mainnet.id) {
+    super(
+      `ENS operations require Ethereum mainnet. ` +
+        `Add chain ID ${chainId} to your chain configuration.`,
+    )
+    this.name = 'EnsNotConfiguredError'
+    this.chainId = chainId
+  }
+}
+
+/**
+ * Thrown when an ENS name cannot be resolved to an address — e.g. the name
+ * is unregistered, resolves to the zero address, or fails normalization.
+ */
+export class EnsResolutionError extends Error {
+  input: string
+
+  constructor(message: string, input: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'EnsResolutionError'
+    this.input = input
+  }
+}
+
+/**
+ * Thrown when an ENS RPC call fails due to a network or provider error.
+ */
+export class EnsRpcError extends Error {
+  input: string
+
+  constructor(message: string, input: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'EnsRpcError'
+    this.input = input
+  }
+}

package/src/ens/index.ts

@@ -0,0 +1,12 @@
+export { EnsNamespace } from './EnsNamespace.js'
+export {
+  EnsNotConfiguredError,
+  EnsResolutionError,
+  EnsRpcError,
+} from './errors.js'
+export {
+  type EnsInfo,
+  type EnsName,
+  isEnsName,
+  type NameServiceProvider,
+} from './types.js'

package/src/ens/types.ts

@@ -0,0 +1,76 @@
+import type { Address } from 'viem'
+
+import type { SwapExecuteParams, SwapQuoteParams } from '@/types/swap/base.js'
+
+/**
+ * A dot-separated ENS name (e.g. `vitalik.eth`, `sub.vitalik.eth`, `example.com`).
+ *
+ * ENS is not limited to `.eth` — it supports any DNSSEC-enabled DNS TLD as well
+ * as ENS-native TLDs (`.eth`, `.test`). Subdomains of arbitrary depth are valid.
+ *
+ * This type is a structural constraint (at least one dot) mirroring viem's Address type.
+ * True validity is determined at runtime by `normalize()` (ENSIP-15): a name is valid
+ * if and only if it does not throw during normalization.
+ */
+export type EnsName = `${string}.${string}`
+
+/**
+ * Type guard for EnsName. Mirrors the pattern of viem's isAddress.
+ * Rejects obviously invalid forms (leading/trailing dots, consecutive dots)
+ * but does not run full ENSIP-15 normalization — use normalize() for that.
+ * @param value - String to check
+ * @returns True if the value satisfies the EnsName structural constraint
+ */
+export function isEnsName(value: string): value is EnsName {
+  return (
+    value.includes('.') &&
+    !value.startsWith('.') &&
+    !value.endsWith('.') &&
+    !value.includes('..')
+  )
+}
+
+/**
+ * Standard ENS profile text record fields as defined by ENSIP-5 and ENSIP-18.
+ * All fields are null when not set on the resolver.
+ */
+export interface EnsInfo {
+  avatar: string | null
+  display: string | null
+  description: string | null
+  url: string | null
+  email: string | null
+  keywords: string | null
+  /** com.twitter */
+  twitter: string | null
+  /** com.github */
+  github: string | null
+  /** com.discord */
+  discord: string | null
+  /** org.reddit */
+  reddit: string | null
+}
+
+/** SwapExecuteParams with recipient narrowed to Address after ENS resolution */
+export type SwapExecuteParamsResolved = Omit<SwapExecuteParams, 'recipient'> & {
+  recipient?: Address
+}
+
+/** SwapQuoteParams with recipient narrowed to Address after ENS resolution */
+export type SwapQuoteParamsResolved = Omit<SwapQuoteParams, 'recipient'> & {
+  recipient?: Address
+}
+
+/**
+ * Common interface for human-readable name service providers.
+ * Implemented by {@link EnsNamespace}; designed to support future providers
+ * such as Basename, Lens, Unstoppable Domains, etc.
+ */
+export interface NameServiceProvider {
+  /** Resolve a name or address to a checksummed hex address. */
+  getAddress(input: Address | EnsName): Promise<Address>
+  /** Reverse-resolve an address to its primary name, or null if not set. */
+  getName(address: Address): Promise<EnsName | null>
+  /** Fetch all standard profile text record fields in a single batched call. */
+  getInfo(input: Address | EnsName): Promise<EnsInfo>
+}

package/src/index.ts

@@ -1,28 +1,74 @@
 export type { Actions } from '@/actions.js'
 export {
+  AAVE,
+  ARB,
+  BAL,
+  CBBTC,
+  CBETH,
+  COMP,
+  CRV,
+  DAI,
+  EETH,
+  ENA,
+  ENS,
   ETH,
+  ETHFI,
+  FRAX,
+  GRT,
+  LDO,
+  LINK,
+  MKR,
   MORPHO,
+  NATIVELY_SUPPORTED_ASSETS,
+  ONDO,
+  ONEINCH,
+  OP,
   OP_DEMO,
+  PENDLE,
+  PEPE,
+  POL,
+  PYUSD,
+  RENDER,
+  RETH,
+  RPL,
+  SHIB,
+  SKY,
+  SNX,
+  STETH,
+  SUSHI,
+  UNI,
   USDC,
   USDC_DEMO,
+  USDE,
+  USDT,
+  WBTC,
+  WEETH,
   WETH,
+  WLD,
+  WSTETH,
 } from '@/constants/assets.js'
 export {
-  SUPPORTED_CHAIN_IDS,
+  ACTIONS_SUPPORTED_CHAIN_IDS,
   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'
+  type EnsInfo,
+  EnsNamespace,
+  EnsNotConfiguredError,
+  EnsResolutionError,
+  EnsRpcError,
+  type NameServiceProvider,
+} from '@/ens/index.js'
+export { LendProvider, MorphoLendProvider } from '@/lend/index.js'
 export {
   SwapProvider,
   type UniswapMarketConfig,
   UniswapSwapProvider,
   type UniswapSwapProviderConfig,
+  type VelodromeMarketConfig,
+  VelodromeSwapProvider,
+  type VelodromeSwapProviderConfig,
 } from '@/swap/index.js'
 export type {
   ActionsConfig,
@@ -45,11 +91,15 @@ export type {
   SwapMarket,
   SwapMarketConfig,
   SwapMarketId,
-  SwapPrice,
-  SwapPriceParams,
   SwapProviderConfig,
+  SwapProviderName,
+  SwapQuote,
+  SwapQuoteExecution,
+  SwapQuoteParams,
   SwapReceipt,
   SwapRoute,
+  SwapRoutingStrategy,
+  SwapSettings,
   SwapTransaction,
   TokenBalance,
   TransactionData,
@@ -58,5 +108,6 @@ export type {
   WalletSwapParams,
 } from '@/types/index.js'
 export { getAssetAddress, isAssetSupportedOnChain } from '@/utils/assets.js'
+export { type EnsName, isEnsName, resolveAddress } from '@/utils/ens.js'
 export { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
 export { SmartWallet } from '@/wallet/core/wallets/smart/abstract/SmartWallet.js'

package/src/lend/__mocks__/MockLendProvider.ts

@@ -59,8 +59,6 @@ export class MockLendProvider extends LendProvider<LendProviderConfig> {
     ) => Promise<LendTransaction>
   >
 
-  protected readonly SUPPORTED_CHAIN_IDS = [1, 130, 8453, 84532] as const
-
   protected readonly SUPPORTED_CHAINS = {
     TESTNET: {
       chainId: 84532,
@@ -70,6 +68,10 @@ export class MockLendProvider extends LendProvider<LendProviderConfig> {
 
   private mockConfig: MockLendProviderConfig
 
+  protocolSupportedChainIds(): number[] {
+    return [1, 130, 8453, 84532]
+  }
+
   constructor(
     config?: LendProviderConfig,
     mockConfig?: Partial<MockLendProviderConfig>,
@@ -77,7 +79,10 @@ export class MockLendProvider extends LendProvider<LendProviderConfig> {
   ) {
     super(
       config || {},
-      chainManager || (new MockChainManager() as unknown as ChainManager),
+      chainManager ||
+        (new MockChainManager({
+          supportedChains: [84532],
+        }) as unknown as ChainManager),
     )
 
     this.mockConfig = {