@eth-optimism/actions-sdk 0.4.0 → 0.6.0

package/src/services/nameservices/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 '@/services/nameservices/ens/utils.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/services/nameservices/ens/__tests__/EnsNamespace.spec.ts

@@ -0,0 +1,173 @@
+import type { Address, PublicClient } from 'viem'
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ChainManager } from '@/services/ChainManager.js'
+import { EnsNamespace } from '@/services/nameservices/ens/EnsNamespace.js'
+import {
+  EnsResolutionError,
+  EnsRpcError,
+} from '@/services/nameservices/ens/errors.js'
+import type { EnsName } from '@/services/nameservices/ens/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/services/nameservices/ens/__tests__/utils.spec.ts

@@ -0,0 +1,105 @@
+import type { Address, PublicClient } from 'viem'
+import { zeroAddress } from 'viem'
+import { describe, expect, it, vi } from 'vitest'
+
+import { resolveAddress } from '@/services/nameservices/ens/utils.js'
+
+const REAL_ADDRESS = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' as Address
+const ZERO_ADDRESS = zeroAddress
+
+function mockClient(
+  returnValue: Address | null,
+  rejects = false,
+): PublicClient {
+  const getEnsAddress = rejects
+    ? vi.fn().mockRejectedValue(new Error('network error'))
+    : vi.fn().mockResolvedValue(returnValue)
+  return { getEnsAddress } as unknown as PublicClient
+}
+
+describe('resolveAddress', () => {
+  describe('hex address input', () => {
+    it('returns a valid hex address as-is', async () => {
+      expect(await resolveAddress(REAL_ADDRESS)).toBe(REAL_ADDRESS)
+    })
+
+    it('does not require a mainnet client for hex addresses', async () => {
+      await expect(resolveAddress(REAL_ADDRESS)).resolves.toBe(REAL_ADDRESS)
+    })
+  })
+
+  describe('ENS name input', () => {
+    it('resolves a valid ENS name', async () => {
+      const client = mockClient(REAL_ADDRESS)
+      const result = await resolveAddress('vitalik.eth', client)
+      expect(result).toBe(REAL_ADDRESS)
+      expect(client.getEnsAddress).toHaveBeenCalledWith({ name: 'vitalik.eth' })
+    })
+
+    it('normalises the ENS name before resolving', async () => {
+      const client = mockClient(REAL_ADDRESS)
+      await resolveAddress('Vitalik.ETH', client)
+      expect(client.getEnsAddress).toHaveBeenCalledWith({ name: 'vitalik.eth' })
+    })
+
+    it('throws EnsNotConfiguredError when no mainnet client is provided', async () => {
+      const { EnsNotConfiguredError } =
+        await import('@/services/nameservices/ens/errors.js')
+      await expect(resolveAddress('vitalik.eth')).rejects.toThrow(
+        EnsNotConfiguredError,
+      )
+    })
+
+    it('includes chain ID 1 in the error when no mainnet client provided', async () => {
+      await expect(resolveAddress('vitalik.eth')).rejects.toThrow('1')
+    })
+
+    it('throws when ENS name cannot be resolved (returns null)', async () => {
+      const client = mockClient(null)
+      await expect(resolveAddress('unresolvable.eth', client)).rejects.toThrow(
+        '"unresolvable.eth" could not be resolved',
+      )
+    })
+
+    it('throws when ENS name resolves to zero address', async () => {
+      const client = mockClient(ZERO_ADDRESS)
+      await expect(resolveAddress('zero.eth', client)).rejects.toThrow(
+        'zero address',
+      )
+    })
+
+    it('throws with RPC error label on network failure', async () => {
+      const client = mockClient(null, true)
+      await expect(resolveAddress('vitalik.eth', client)).rejects.toThrow(
+        'RPC error',
+      )
+    })
+
+    it('preserves the original cause on RPC failure', async () => {
+      const client = mockClient(null, true)
+      let caught: Error | undefined
+      try {
+        await resolveAddress('vitalik.eth', client)
+      } catch (e) {
+        caught = e as Error
+      }
+      expect(caught?.cause).toBeInstanceOf(Error)
+      expect((caught?.cause as Error).message).toBe('network error')
+    })
+  })
+
+  describe('invalid input', () => {
+    it('throws for ENS-shaped strings that fail normalisation', async () => {
+      // Has a dot so satisfies EnsName, but contains invalid ENS characters
+      await expect(
+        resolveAddress('not!valid.eth', {} as PublicClient),
+      ).rejects.toThrow('Invalid address or ENS name')
+    })
+
+    it('includes the invalid input in the error message', async () => {
+      await expect(
+        resolveAddress('!!bad!!.eth', {} as PublicClient),
+      ).rejects.toThrow('"!!bad!!.eth"')
+    })
+  })
+})

package/src/services/nameservices/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/services/nameservices/ens/index.ts

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

package/src/services/nameservices/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>
+}