ethagent 1.1.1 → 2.0.0

package/src/identity/ens/ensAutomation/read.ts

@@ -0,0 +1,114 @@
+import {
+  createPublicClient,
+  fallback,
+  getAddress,
+  http,
+  type Address,
+  type Hex,
+  type PublicClient,
+} from 'viem'
+import { mainnet } from 'viem/chains'
+import {
+  AGENT_RECORD_READ_KEY_LIST,
+  recordsFromTextMap,
+  type AgentEnsRecordState,
+} from '../agentRecords.js'
+import {
+  ENS_AUTOMATION_NAME_WRAPPER_ABI,
+  ENS_AUTOMATION_REGISTRY_ABI,
+  ENS_AUTOMATION_RESOLVER_ABI,
+  ENS_NAME_WRAPPER_ADDRESS_MAINNET,
+  ENS_REGISTRY_ADDRESS_MAINNET,
+  ENS_RPC_URLS,
+  ZERO_ADDRESS,
+} from './contracts.js'
+import type { EnsAutomationReadClient } from './types.js'
+
+export function shortHex(value: string): string {
+  if (value.length <= 14) return value
+  return `${value.slice(0, 6)}...${value.slice(-4)}`
+}
+
+export function createEnsAutomationClient(): PublicClient {
+  const transports = ENS_RPC_URLS.map(url => http(url, { retryCount: 0, timeout: 8_000 }))
+  return createPublicClient({
+    chain: mainnet,
+    transport: transports.length === 1 ? transports[0]! : fallback(transports, { retryCount: 0 }),
+  })
+}
+
+export async function readOwner(client: EnsAutomationReadClient, node: Hex): Promise<Address> {
+  const owner = await client.readContract({
+    address: ENS_REGISTRY_ADDRESS_MAINNET,
+    abi: ENS_AUTOMATION_REGISTRY_ABI,
+    functionName: 'owner',
+    args: [node],
+  }) as Address
+  return getAddress(owner)
+}
+
+export async function readResolver(client: EnsAutomationReadClient, node: Hex): Promise<Address> {
+  const resolver = await client.readContract({
+    address: ENS_REGISTRY_ADDRESS_MAINNET,
+    abi: ENS_AUTOMATION_REGISTRY_ABI,
+    functionName: 'resolver',
+    args: [node],
+  }) as Address
+  return getAddress(resolver)
+}
+
+export async function readWrappedOwner(client: EnsAutomationReadClient, node: Hex): Promise<Address> {
+  const owner = await client.readContract({
+    address: ENS_NAME_WRAPPER_ADDRESS_MAINNET,
+    abi: ENS_AUTOMATION_NAME_WRAPPER_ABI,
+    functionName: 'ownerOf',
+    args: [BigInt(node)],
+  }) as Address
+  return getAddress(owner)
+}
+
+export async function readAddressRecord(client: EnsAutomationReadClient, resolverAddress: Address, node: Hex): Promise<Address | null> {
+  try {
+    const addr = await client.readContract({
+      address: resolverAddress,
+      abi: ENS_AUTOMATION_RESOLVER_ABI,
+      functionName: 'addr',
+      args: [node],
+    }) as Address
+    return isZero(addr) ? null : getAddress(addr)
+  } catch {
+    return null
+  }
+}
+
+export async function readTextRecords(client: EnsAutomationReadClient, resolverAddress: Address, node: Hex): Promise<AgentEnsRecordState> {
+  const text: Record<string, string> = {}
+  for (const key of AGENT_RECORD_READ_KEY_LIST) {
+    try {
+      const value = await client.readContract({
+        address: resolverAddress,
+        abi: ENS_AUTOMATION_RESOLVER_ABI,
+        functionName: 'text',
+        args: [node, key],
+      }) as string
+      if (value) text[key] = value
+    } catch {
+    }
+  }
+  return recordsFromTextMap(text)
+}
+
+export function isZero(address: Address): boolean {
+  return address.toLowerCase() === ZERO_ADDRESS
+}
+
+export function sameAddress(a: Address, b: Address): boolean {
+  return a.toLowerCase() === b.toLowerCase()
+}
+
+export function normalizeAgentRecords(records: AgentEnsRecordState): AgentEnsRecordState {
+  return {
+    ...records,
+    ...(records.token ? { token: records.token.toLowerCase() } : {}),
+  }
+}

package/src/identity/ens/ensAutomation/root.ts

@@ -0,0 +1,63 @@
+import { getAddress, namehash, type Address } from 'viem'
+import { normalizeEthDomain } from '../ensLookup.js'
+import { validateErc8004TokenOwner } from '../../registry/erc8004.js'
+import { ENS_NAME_WRAPPER_ADDRESS_MAINNET } from './contracts.js'
+import { isRootEthName } from './names.js'
+import {
+  createEnsAutomationClient,
+  isZero,
+  readOwner,
+  readWrappedOwner,
+  sameAddress,
+  shortHex,
+} from './read.js'
+import type {
+  EnsRootPreflightArgs,
+  EnsRootPreflightResult,
+} from './types.js'
+
+export async function preflightEnsRoot(args: EnsRootPreflightArgs): Promise<EnsRootPreflightResult> {
+  const rootName = normalizeEthDomain(args.rootName)
+  if (!isRootEthName(rootName)) {
+    return { ok: false, reason: 'invalid-root', detail: 'Enter the parent .eth name, e.g. name.eth' }
+  }
+  if (args.agentId === undefined || args.agentId === '') {
+    return { ok: false, reason: 'missing-token-id', detail: 'this identity is missing an ERC-8004 token id' }
+  }
+  const expectedOwnerAddress = getAddress(args.expectedOwnerAddress)
+  const client = args.ensClient ?? createEnsAutomationClient()
+  const rootNode = namehash(rootName)
+  let rootOwner: Address
+  try {
+    rootOwner = await readOwner(client, rootNode)
+  } catch (err: unknown) {
+    return { ok: false, reason: 'lookup-failed', detail: err instanceof Error ? err.message : String(err) }
+  }
+  if (isZero(rootOwner)) {
+    return { ok: false, reason: 'root-not-owned', detail: `${rootName} does not have an ENS manager on Ethereum mainnet` }
+  }
+  const parentWrapped = sameAddress(rootOwner, ENS_NAME_WRAPPER_ADDRESS_MAINNET)
+  let ownerAddress: Address
+  try {
+    ownerAddress = parentWrapped ? await readWrappedOwner(client, rootNode) : getAddress(rootOwner)
+  } catch (err: unknown) {
+    return { ok: false, reason: 'wrapped-parent', detail: err instanceof Error ? err.message : String(err) }
+  }
+  if (!sameAddress(ownerAddress, expectedOwnerAddress)) {
+    return {
+      ok: false,
+      reason: 'root-owner-mismatch',
+      detail: `${rootName} is managed by ${shortHex(ownerAddress)}, not the connected wallet ${shortHex(expectedOwnerAddress)}`,
+    }
+  }
+  const tokenOwner = await validateErc8004TokenOwner({
+    ...args.registry,
+    agentId: typeof args.agentId === 'bigint' ? args.agentId : BigInt(args.agentId),
+    expectedOwner: ownerAddress,
+    publicClient: args.tokenPublicClient,
+  })
+  if (!tokenOwner.ok) {
+    return { ok: false, reason: tokenOwner.reason, detail: tokenOwner.detail }
+  }
+  return { ok: true, ownerAddress }
+}

package/src/identity/ens/ensAutomation/setup.ts

@@ -0,0 +1,284 @@
+import { getAddress, namehash, type Address } from 'viem'
+import {
+  buildAgentEnsRecords,
+  diffRecords,
+} from '../agentRecords.js'
+import { normalizeEthDomain, splitSubdomainName } from '../ensLookup.js'
+import { validateErc8004TokenOwner } from '../../registry/erc8004.js'
+import {
+  ENS_NAME_WRAPPER_ADDRESS_MAINNET,
+  ENS_PUBLIC_RESOLVER_ADDRESS_MAINNET,
+} from './contracts.js'
+import {
+  createEnsAutomationClient,
+  isZero,
+  normalizeAgentRecords,
+  readAddressRecord,
+  readOwner,
+  readResolver,
+  readTextRecords,
+  readWrappedOwner,
+  sameAddress,
+  shortHex,
+} from './read.js'
+import {
+  hasValidSubdomainParts,
+  isRootEthName,
+  isValidSubdomainLabel,
+} from './names.js'
+import type {
+  EnsSetupBlockedPlan,
+  EnsSetupPreflight,
+  EnsSetupPreflightArgs,
+  EnsRegistryAction,
+} from './types.js'
+
+export async function preflightEnsSetup(args: EnsSetupPreflightArgs): Promise<EnsSetupPreflight> {
+  const rootName = normalizeEthDomain(args.rootName)
+  const label = args.label.trim().toLowerCase()
+  const operatorAddress = getAddress(args.operatorAddress)
+  const mode = args.mode ?? 'advanced'
+  const fullName = `${label}.${rootName}`
+
+  if (!isRootEthName(rootName)) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      reason: 'invalid-root',
+      detail: 'Enter the parent .eth name, e.g. name.eth',
+    })
+  }
+  if (!isValidSubdomainLabel(label) || !hasValidSubdomainParts(fullName)) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      reason: 'invalid-label',
+      detail: 'Agent subdomain can use lowercase letters, numbers, and hyphens only',
+    })
+  }
+  if (args.agentId === undefined || args.agentId === '') {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      reason: 'missing-token-id',
+      detail: 'This identity is missing an ERC-8004 token id',
+    })
+  }
+
+  const client = args.ensClient ?? createEnsAutomationClient()
+  const rootNode = namehash(rootName)
+  const fullNode = namehash(fullName)
+
+  let rootOwner: Address
+  try {
+    rootOwner = await readOwner(client, rootNode)
+  } catch (err: unknown) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      reason: 'lookup-failed',
+      detail: err instanceof Error ? err.message : String(err),
+    })
+  }
+
+  if (isZero(rootOwner)) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      reason: 'root-not-owned',
+      detail: `${rootName} does not have an ENS manager on Ethereum mainnet`,
+    })
+  }
+  const parentWrapped = sameAddress(rootOwner, ENS_NAME_WRAPPER_ADDRESS_MAINNET)
+  let ownerAddress: Address
+  try {
+    ownerAddress = parentWrapped
+      ? await readWrappedOwner(client, rootNode)
+      : getAddress(rootOwner)
+  } catch (err: unknown) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      reason: 'wrapped-parent',
+      detail: err instanceof Error ? err.message : String(err),
+    })
+  }
+  const expectedOwnerAddress = args.expectedOwnerAddress ? getAddress(args.expectedOwnerAddress) : null
+  if (expectedOwnerAddress && !sameAddress(ownerAddress, expectedOwnerAddress)) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      ownerAddress,
+      reason: 'root-owner-mismatch',
+      detail: `${rootName} is managed by ${shortHex(ownerAddress)}, not the connected wallet ${shortHex(expectedOwnerAddress)}`,
+    })
+  }
+  if (!args.allowSameOwnerOperator && sameAddress(ownerAddress, operatorAddress)) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      ownerAddress,
+      reason: 'operator-matches-owner',
+      detail: 'Operator wallet must be different from the owner wallet that owns the ERC-8004 token and parent ENS name',
+    })
+  }
+
+  const tokenOwner = await validateErc8004TokenOwner({
+    ...args.registry,
+    agentId: typeof args.agentId === 'bigint' ? args.agentId : BigInt(args.agentId),
+    expectedOwner: ownerAddress,
+    publicClient: args.tokenPublicClient,
+  })
+  if (!tokenOwner.ok) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      ownerAddress,
+      reason: tokenOwner.reason,
+      detail: tokenOwner.detail,
+    })
+  }
+
+  let childOwner: Address
+  let childResolver: Address
+  try {
+    childOwner = await readOwner(client, fullNode)
+    childResolver = await readResolver(client, fullNode)
+  } catch (err: unknown) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      ownerAddress,
+      reason: 'lookup-failed',
+      detail: err instanceof Error ? err.message : String(err),
+    })
+  }
+
+  let registryAction: EnsRegistryAction = 'none'
+  let resolverAddress = getAddress(childResolver)
+  if (isZero(childOwner)) {
+    registryAction = parentWrapped ? 'create-wrapped-subdomain' : 'create-subdomain'
+    resolverAddress = ENS_PUBLIC_RESOLVER_ADDRESS_MAINNET
+  } else if (sameAddress(childOwner, ENS_NAME_WRAPPER_ADDRESS_MAINNET)) {
+    let wrappedChildOwner: Address
+    try {
+      wrappedChildOwner = await readWrappedOwner(client, fullNode)
+    } catch (err: unknown) {
+      return manual(args, {
+        rootName,
+        label,
+        fullName,
+        operatorAddress,
+        ownerAddress,
+        reason: 'subdomain-wrapped',
+        detail: err instanceof Error ? err.message : String(err),
+      })
+    }
+    if (!sameAddress(wrappedChildOwner, ownerAddress)) {
+      return manual(args, {
+        rootName,
+        label,
+        fullName,
+        operatorAddress,
+        ownerAddress,
+        reason: 'subdomain-owned-by-other',
+        detail: `${fullName} is wrapped and owned by ${getAddress(wrappedChildOwner)}`,
+      })
+    }
+    if (isZero(childResolver)) {
+      registryAction = 'set-wrapped-resolver'
+      resolverAddress = ENS_PUBLIC_RESOLVER_ADDRESS_MAINNET
+    }
+  } else if (!sameAddress(childOwner, ownerAddress)) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      ownerAddress,
+      reason: 'subdomain-owned-by-other',
+      detail: `${fullName} is managed by ${shortHex(getAddress(childOwner))}`,
+    })
+  } else if (isZero(childResolver)) {
+    registryAction = 'set-resolver'
+    resolverAddress = ENS_PUBLIC_RESOLVER_ADDRESS_MAINNET
+  }
+
+  const currentAddress = isZero(childResolver) ? null : await readAddressRecord(client, resolverAddress, fullNode)
+  const currentRecords = normalizeAgentRecords(isZero(childResolver) ? {} : await readTextRecords(client, resolverAddress, fullNode))
+  const nextRecords = buildAgentEnsRecords({
+    chainId: args.registry.chainId,
+    identityRegistryAddress: args.registry.identityRegistryAddress,
+    agentId: String(args.agentId),
+    agentCardCid: args.agentCardCid,
+  })
+  if (currentRecords.token && nextRecords.token && currentRecords.token !== nextRecords.token) {
+    return manual(args, {
+      rootName,
+      label,
+      fullName,
+      operatorAddress,
+      ownerAddress,
+      resolverAddress,
+      reason: 'token-record-collision',
+      detail: `${fullName} already points to another ERC-8004 token`,
+      currentRecords,
+      nextRecords,
+    })
+  }
+
+  const recordDiffs = diffRecords(currentRecords, nextRecords)
+  const addressChanged = !currentAddress || !sameAddress(currentAddress, ownerAddress)
+  const needsRegistryTx = registryAction !== 'none'
+  const needsRecordsTx = addressChanged || recordDiffs.some(diff => diff.changed)
+  return {
+    ok: true,
+    setup: {
+      mode,
+      rootName,
+      label,
+      fullName,
+      ownerAddress,
+      operatorAddress,
+      resolverAddress,
+      registryAction,
+      addressRecord: {
+        current: currentAddress,
+        next: ownerAddress,
+        changed: addressChanged,
+      },
+      currentRecords,
+      nextRecords,
+      recordDiffs,
+      txCount: (needsRegistryTx ? 1 : 0) + (needsRecordsTx ? 1 : 0),
+      warnings: [],
+    },
+  }
+}
+
+function manual(
+  args: EnsSetupPreflightArgs,
+  fallback: Omit<EnsSetupBlockedPlan, 'mode'> & Partial<Pick<EnsSetupBlockedPlan, 'mode'>>,
+): EnsSetupPreflight {
+  return { ok: false, fallback: { ...fallback, mode: args.mode ?? 'advanced' } }
+}

package/src/identity/ens/ensAutomation/transactions.ts

@@ -0,0 +1,107 @@
+import {
+  encodeFunctionData,
+  labelhash,
+  namehash,
+} from 'viem'
+import {
+  DEFAULT_EXPIRY,
+  DEFAULT_FUSES,
+  DEFAULT_TTL,
+  ENS_AUTOMATION_NAME_WRAPPER_ABI,
+  ENS_AUTOMATION_REGISTRY_ABI,
+  ENS_AUTOMATION_RESOLVER_ABI,
+  ENS_NAME_WRAPPER_ADDRESS_MAINNET,
+  ENS_REGISTRY_ADDRESS_MAINNET,
+  ZERO_ADDRESS,
+} from './contracts.js'
+import type {
+  EncodedEnsTransaction,
+  EnsSetupPlan,
+} from './types.js'
+
+export function encodeEnsRegistryTransaction(setup: EnsSetupPlan): EncodedEnsTransaction | null {
+  const rootNode = namehash(setup.rootName)
+  const fullNode = namehash(setup.fullName)
+  if (setup.registryAction === 'create-subdomain') {
+    const data = encodeFunctionData({
+      abi: ENS_AUTOMATION_REGISTRY_ABI,
+      functionName: 'setSubnodeRecord',
+      args: [rootNode, labelhash(setup.label), setup.ownerAddress, setup.resolverAddress, DEFAULT_TTL],
+    })
+    return { to: ENS_REGISTRY_ADDRESS_MAINNET, data, calls: [data] }
+  }
+  if (setup.registryAction === 'create-wrapped-subdomain') {
+    const data = encodeFunctionData({
+      abi: ENS_AUTOMATION_NAME_WRAPPER_ABI,
+      functionName: 'setSubnodeRecord',
+      args: [rootNode, setup.label, setup.ownerAddress, setup.resolverAddress, DEFAULT_TTL, DEFAULT_FUSES, DEFAULT_EXPIRY],
+    })
+    return { to: ENS_NAME_WRAPPER_ADDRESS_MAINNET, data, calls: [data] }
+  }
+  if (setup.registryAction === 'set-resolver') {
+    const data = encodeFunctionData({
+      abi: ENS_AUTOMATION_REGISTRY_ABI,
+      functionName: 'setResolver',
+      args: [fullNode, setup.resolverAddress],
+    })
+    return { to: ENS_REGISTRY_ADDRESS_MAINNET, data, calls: [data] }
+  }
+  if (setup.registryAction === 'set-wrapped-resolver') {
+    const data = encodeFunctionData({
+      abi: ENS_AUTOMATION_NAME_WRAPPER_ABI,
+      functionName: 'setResolver',
+      args: [fullNode, setup.resolverAddress],
+    })
+    return { to: ENS_NAME_WRAPPER_ADDRESS_MAINNET, data, calls: [data] }
+  }
+  return null
+}
+
+export function encodeEnsRecordsTransaction(setup: EnsSetupPlan): EncodedEnsTransaction | null {
+  const node = namehash(setup.fullName)
+  const calls: `0x${string}`[] = []
+  if (setup.addressRecord.changed) {
+    calls.push(encodeFunctionData({
+      abi: ENS_AUTOMATION_RESOLVER_ABI,
+      functionName: 'setAddr',
+      args: [node, setup.addressRecord.next],
+    }))
+  }
+  for (const diff of setup.recordDiffs) {
+    if (!diff.changed) continue
+    calls.push(encodeFunctionData({
+      abi: ENS_AUTOMATION_RESOLVER_ABI,
+      functionName: 'setText',
+      args: [node, diff.key, diff.next],
+    }))
+  }
+  if (calls.length === 0) return null
+  const data = calls.length === 1
+    ? calls[0]!
+    : encodeFunctionData({
+        abi: ENS_AUTOMATION_RESOLVER_ABI,
+        functionName: 'multicall',
+        args: [calls],
+      })
+  return { to: setup.resolverAddress, data, calls }
+}
+
+export function encodeDeleteSubnodeRegistry(parentName: string, label: string): EncodedEnsTransaction {
+  const parentNode = namehash(parentName)
+  const data = encodeFunctionData({
+    abi: ENS_AUTOMATION_REGISTRY_ABI,
+    functionName: 'setSubnodeRecord',
+    args: [parentNode, labelhash(label), ZERO_ADDRESS, ZERO_ADDRESS, DEFAULT_TTL],
+  })
+  return { to: ENS_REGISTRY_ADDRESS_MAINNET, data, calls: [data] }
+}
+
+export function encodeDeleteSubnodeWrapped(parentName: string, label: string): EncodedEnsTransaction {
+  const parentNode = namehash(parentName)
+  const data = encodeFunctionData({
+    abi: ENS_AUTOMATION_NAME_WRAPPER_ABI,
+    functionName: 'setSubnodeRecord',
+    args: [parentNode, label, ZERO_ADDRESS, ZERO_ADDRESS, DEFAULT_TTL, DEFAULT_FUSES, DEFAULT_EXPIRY],
+  })
+  return { to: ENS_NAME_WRAPPER_ADDRESS_MAINNET, data, calls: [data] }
+}

package/src/identity/ens/ensAutomation/types.ts

@@ -0,0 +1,126 @@
+import type { Address, Hex, PublicClient } from 'viem'
+import type {
+  AgentEnsRecordState,
+  AgentEnsRecords,
+  AgentRecordDiff,
+} from '../agentRecords.js'
+import {
+  validateErc8004TokenOwner,
+  type Erc8004RegistryConfig,
+} from '../../registry/erc8004.js'
+
+export type EnsAutomationReadClient = Pick<PublicClient, 'readContract'>
+export type TokenOwnerReadClient = Parameters<typeof validateErc8004TokenOwner>[0]['publicClient']
+
+export type EnsRegistryAction = 'create-subdomain' | 'set-resolver' | 'create-wrapped-subdomain' | 'set-wrapped-resolver' | 'none'
+
+export type EnsSetupPlan = {
+  mode: 'simple' | 'advanced'
+  rootName: string
+  label: string
+  fullName: string
+  ownerAddress: Address
+  operatorAddress: Address
+  resolverAddress: Address
+  registryAction: EnsRegistryAction
+  addressRecord: {
+    current: Address | null
+    next: Address
+    changed: boolean
+  }
+  currentRecords: AgentEnsRecordState
+  nextRecords: AgentEnsRecords
+  recordDiffs: AgentRecordDiff[]
+  txCount: number
+  warnings: string[]
+}
+
+export type EnsSetupBlockedPlan = {
+  mode: 'simple' | 'advanced'
+  rootName: string
+  label: string
+  fullName: string
+  operatorAddress: Address
+  ownerAddress?: Address
+  resolverAddress?: Address
+  reason:
+    | 'invalid-root'
+    | 'invalid-label'
+    | 'missing-token-id'
+    | 'root-not-owned'
+    | 'root-owner-mismatch'
+    | 'wrapped-parent'
+    | 'parent-missing-resolver'
+    | 'subdomain-owned-by-other'
+    | 'subdomain-wrapped'
+    | 'operator-matches-owner'
+    | 'token-owner-mismatch'
+    | 'token-owner-lookup-failed'
+    | 'token-record-collision'
+    | 'lookup-failed'
+  detail: string
+  currentRecords?: AgentEnsRecordState
+  nextRecords?: AgentEnsRecords
+}
+
+export type EnsSetupPreflight =
+  | { ok: true; setup: EnsSetupPlan }
+  | { ok: false; fallback: EnsSetupBlockedPlan }
+
+export type EncodedEnsTransaction = {
+  to: Address
+  data: Hex
+  calls: Hex[]
+}
+
+export type EnsSetupPreflightArgs = {
+  rootName: string
+  label: string
+  operatorAddress: Address
+  mode?: 'simple' | 'advanced'
+  expectedOwnerAddress?: Address
+  allowSameOwnerOperator?: boolean
+  registry: Erc8004RegistryConfig
+  agentId: string | bigint | undefined
+  agentCardCid?: string
+  ensClient?: EnsAutomationReadClient
+  tokenPublicClient?: TokenOwnerReadClient
+}
+
+export type EnsRootPreflightArgs = {
+  rootName: string
+  expectedOwnerAddress: Address
+  registry: Erc8004RegistryConfig
+  agentId: string | bigint | undefined
+  ensClient?: EnsAutomationReadClient
+  tokenPublicClient?: TokenOwnerReadClient
+}
+
+export type EnsRootPreflightResult =
+  | { ok: true; ownerAddress: Address }
+  | { ok: false; reason: 'invalid-root' | 'missing-token-id' | 'root-not-owned' | 'wrapped-parent' | 'root-owner-mismatch' | 'token-owner-mismatch' | 'token-owner-lookup-failed' | 'lookup-failed'; detail: string }
+
+export type EnsSubdomainDeletePlan = {
+  fullName: string
+  parentName: string
+  label: string
+  parentWrapped: boolean
+  parentOwnerAddress: Address
+  transaction: EncodedEnsTransaction
+}
+
+export type EnsSubdomainDeletePreflightArgs = {
+  fullName: string
+  expectedOwnerAddress: Address
+  ensClient?: EnsAutomationReadClient
+}
+
+export type EnsSubdomainDeletePreflightResult =
+  | { ok: true; plan: EnsSubdomainDeletePlan }
+  | { ok: false; reason: 'invalid-name' | 'not-a-subdomain' | 'lookup-failed' | 'parent-not-owned' | 'parent-owner-mismatch' | 'subdomain-missing'; detail: string }
+
+export type OperatorSetDiff = {
+  inSync: boolean
+  metadataOnly: Address[]
+  resolverOnly: Address[]
+}