@eth-optimism/actions-sdk 0.4.0 → 0.5.0

package/dist/wallet/core/wallets/abstract/Wallet.js

@@ -1,3 +1,4 @@
+import { EnsNamespace } from '../../../../ens/index.js';
 import { WalletLendNamespace } from '../../../../lend/namespaces/WalletLendNamespace.js';
 import { fetchERC20Balance, fetchETHBalance } from '../../../../services/tokenBalance.js';
 import { WalletSwapNamespace } from '../../../../swap/namespaces/WalletSwapNamespace.js';
@@ -23,7 +24,8 @@ export class Wallet {
             this.lend = new WalletLendNamespace(this.lendProviders, this);
         }
         if (Object.values(this.swapProviders).some(Boolean)) {
-            this.swap = new WalletSwapNamespace(this.swapProviders, this, swapSettings);
+            const ens = new EnsNamespace(this.chainManager);
+            this.swap = new WalletSwapNamespace(this.swapProviders, this, (r) => (r ? ens.getAddress(r) : Promise.resolve(undefined)), swapSettings);
         }
     }
     /**

package/dist/wallet/core/wallets/abstract/Wallet.js.map

@@ -1 +1 @@
-{"version":3,"file":"Wallet.js","sourceRoot":"","sources":["../../../../../src/wallet/core/wallets/abstract/Wallet.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAA;AAE9E,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAA;AAU9E;;;;GAIG;AACH,MAAM,OAAgB,MAAM;IA+B1B;;;;;;OAMG;IACH,YACE,YAA0B,EAC1B,aAA6B,EAC7B,aAA6B,EAC7B,eAAyB,EACzB,YAA2B;QAE3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;QAChC,IAAI,CAAC,aAAa,GAAG,aAAa,IAAI,EAAE,CAAA;QACxC,IAAI,CAAC,aAAa,GAAG,aAAa,IAAI,EAAE,CAAA;QACxC,IAAI,CAAC,eAAe,GAAG,eAAe,IAAI,EAAE,CAAA;QAC5C,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;YACzD,IAAI,CAAC,IAAI,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;QAC/D,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACpD,IAAI,CAAC,IAAI,GAAG,IAAI,mBAAmB,CACjC,IAAI,CAAC,aAAa,EAClB,IAAI,EACJ,YAAY,CACb,CAAA;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU;QACd,MAAM,oBAAoB,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YACpE,OAAO,iBAAiB,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QAClE,CAAC,CAAC,CAAA;QACF,MAAM,iBAAiB,GAAG,eAAe,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;QAE1E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,iBAAiB,EAAE,GAAG,oBAAoB,CAAC,CAAC,CAAA;IAClE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACO,KAAK,CAAC,qBAAqB,KAAmB,CAAC;IAEzD;;;;;;;;;;;;OAYG;IACO,KAAK,CAAC,UAAU;QACxB,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC,WAAW,CAAA;QAC7C,IAAI,CAAC,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;YAC7B,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,qBAAqB,EAAE,CAAA;YACpC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,sDAAsD;gBACtD,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;gBAC5B,MAAM,IAAI,KAAK,CAAC,6BAA6B,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;YAClE,CAAC;QACH,CAAC,CAAC,EAAE,CAAA;QACJ,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;CAyBF"}
+{"version":3,"file":"Wallet.js","sourceRoot":"","sources":["../../../../../src/wallet/core/wallets/abstract/Wallet.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAA;AAE9E,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAA;AAU9E;;;;GAIG;AACH,MAAM,OAAgB,MAAM;IA+B1B;;;;;;OAMG;IACH,YACE,YAA0B,EAC1B,aAA6B,EAC7B,aAA6B,EAC7B,eAAyB,EACzB,YAA2B;QAE3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;QAChC,IAAI,CAAC,aAAa,GAAG,aAAa,IAAI,EAAE,CAAA;QACxC,IAAI,CAAC,aAAa,GAAG,aAAa,IAAI,EAAE,CAAA;QACxC,IAAI,CAAC,eAAe,GAAG,eAAe,IAAI,EAAE,CAAA;QAC5C,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;YACzD,IAAI,CAAC,IAAI,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;QAC/D,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACpD,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;YAC/C,IAAI,CAAC,IAAI,GAAG,IAAI,mBAAmB,CACjC,IAAI,CAAC,aAAa,EAClB,IAAI,EACJ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAC3D,YAAY,CACb,CAAA;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU;QACd,MAAM,oBAAoB,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YACpE,OAAO,iBAAiB,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QAClE,CAAC,CAAC,CAAA;QACF,MAAM,iBAAiB,GAAG,eAAe,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;QAE1E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,iBAAiB,EAAE,GAAG,oBAAoB,CAAC,CAAC,CAAA;IAClE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACO,KAAK,CAAC,qBAAqB,KAAmB,CAAC;IAEzD;;;;;;;;;;;;OAYG;IACO,KAAK,CAAC,UAAU;QACxB,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC,WAAW,CAAA;QAC7C,IAAI,CAAC,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;YAC7B,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,qBAAqB,EAAE,CAAA;YACpC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,sDAAsD;gBACtD,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;gBAC5B,MAAM,IAAI,KAAK,CAAC,6BAA6B,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;YAClE,CAAC;QACH,CAAC,CAAC,EAAE,CAAA;QACJ,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;CAyBF"}

package/package.json

@@ -11,7 +11,7 @@
   },
   "type": "module",
   "sideEffects": false,
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TypeScript SDK for Actions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/actions.ts

@@ -1,3 +1,4 @@
+import { EnsNamespace } from '@/ens/index.js'
 import { AaveLendProvider, MorphoLendProvider } from '@/lend/index.js'
 import { ActionsLendNamespace } from '@/lend/namespaces/ActionsLendNamespace.js'
 import { ChainManager } from '@/services/ChainManager.js'
@@ -47,6 +48,7 @@ export class Actions<
     SmartWalletProvider
   >
   private chainManager: ChainManager
+  private _ens: EnsNamespace
   private _lend?: ActionsLendNamespace
   private _lendProviders: LendProviders = {}
   private _swap?: ActionsSwapNamespace
@@ -76,6 +78,8 @@ export class Actions<
     this._assetsConfig = config.assets
     validateConfigAddresses(config)
 
+    this._ens = new EnsNamespace(this.chainManager)
+
     if (config.lend?.morpho) {
       this._lendProviders.morpho = new MorphoLendProvider(
         config.lend.morpho,
@@ -111,6 +115,7 @@ export class Actions<
     if (Object.values(this._swapProviders).some(Boolean)) {
       this._swap = new ActionsSwapNamespace(
         this._swapProviders,
+        (r) => (r ? this._ens.getAddress(r) : Promise.resolve(undefined)),
         this._swapSettings,
       )
     }
@@ -142,6 +147,16 @@ export class Actions<
     return this._lendProviders
   }
 
+  /**
+   * Get ENS operations interface
+   * @description Access to Ethereum Name Service operations: resolve, reverseResolve, lookupText.
+   * Requires Ethereum mainnet (chain ID 1) to be included in your chain configuration.
+   * @returns EnsNamespace for ENS operations
+   */
+  get ens(): EnsNamespace {
+    return this._ens
+  }
+
   /**
    * Get swap operations interface
    * @description Access to swap operations like price quotes and markets.

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

@@ -52,6 +52,14 @@ export {
   type SupportedChainId,
 } from '@/constants/supportedChains.js'
 export * from '@/core/error/errors.js'
+export {
+  type EnsInfo,
+  EnsNamespace,
+  EnsNotConfiguredError,
+  EnsResolutionError,
+  EnsRpcError,
+  type NameServiceProvider,
+} from '@/ens/index.js'
 export { LendProvider, MorphoLendProvider } from '@/lend/index.js'
 export {
   SwapProvider,
@@ -100,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/services/ChainManager.ts

@@ -49,6 +49,16 @@ export class ChainManager {
     return client
   }
 
+  /**
+   * Get public client for a specific chain, or undefined if not configured.
+   * Use this when the chain is optional (e.g. mainnet for ENS resolution).
+   * @param chainId - The chain ID to retrieve the public client for
+   * @returns PublicClient instance, or undefined if not configured
+   */
+  tryGetPublicClient(chainId: SupportedChainId): PublicClient | undefined {
+    return this.publicClients.get(chainId)
+  }
+
   /**
    * Get bundler client for a specific chain
    * @param chainId - The chain ID to retrieve the bundler client for

package/src/services/__mocks__/MockChainManager.ts

@@ -21,6 +21,9 @@ export class MockChainManager {
   public getPublicClient: MockedFunction<
     (chainId: SupportedChainId) => PublicClient
   >
+  public tryGetPublicClient: MockedFunction<
+    (chainId: SupportedChainId) => PublicClient | undefined
+  >
   public getBundlerClient: MockedFunction<
     (chainId: SupportedChainId, account: SmartAccount) => BundlerClient
   >
@@ -54,6 +57,11 @@ export class MockChainManager {
         }
         return client
       })
+    this.tryGetPublicClient = vi
+      .fn()
+      .mockImplementation((chainId: SupportedChainId) => {
+        return this.publicClients.get(chainId)
+      })
     this.getBundlerClient = vi
       .fn()
       .mockImplementation((chainId: SupportedChainId) => {