ethagent 1.1.2 → 2.0.0

package/src/identity/registry/erc8004/metadata.ts

@@ -0,0 +1,335 @@
+import { getAddress, isAddress, type Address } from 'viem'
+import type { TransferSnapshotMetadata } from '../../../storage/config.js'
+import type { WalletContinuityRestoreAccessKey } from '../../continuity/envelope.js'
+import { readOwnerAddressField } from '../../identityCompat.js'
+import { arrayField, numberField, objectField, stringField } from '../fieldParsers.js'
+import type {
+  ApprovedOperatorWalletRecord,
+  EthagentBackupPointer,
+  EthagentOperatorsPointer,
+  EthagentPublicDiscoveryPointer,
+  EthagentRegistrationPointer,
+} from './types.js'
+
+export function parseEthagentBackupPointer(registration: Record<string, unknown> | null): EthagentBackupPointer | null {
+  if (!registration) return null
+  const ext = objectField(registration, 'x-ethagent') ?? objectField(registration, 'ethagent')
+  const backup = ext ? objectField(ext, 'backup') : null
+  const cid = backup ? stringField(backup, 'cid') : undefined
+  if (!cid) return null
+  const agentAddress = stringField(ext, 'agentAddress')
+  const transferSnapshot = backup ? parseTransferSnapshotMetadata(objectField(backup, 'transferSnapshot')) : undefined
+  const pastBackupsArray = arrayField(backup ?? {}, 'pastBackups')
+  const pastBackups = pastBackupsArray?.flatMap(item => {
+    if (!item || typeof item !== 'object') return []
+    const obj = item as Record<string, unknown>
+    const itemCid = stringField(obj, 'cid')
+    if (!itemCid) return []
+    return [{
+      cid: itemCid,
+      ...(stringField(obj, 'createdAt') ? { createdAt: stringField(obj, 'createdAt') } : {}),
+    }]
+  })
+
+  return {
+    cid,
+    envelopeVersion: backup ? stringField(backup, 'envelopeVersion') : undefined,
+    createdAt: backup ? stringField(backup, 'createdAt') : undefined,
+    ...(agentAddress && isAddress(agentAddress) ? { agentAddress: getAddress(agentAddress) } : {}),
+    ...(transferSnapshot ? { transferSnapshot } : {}),
+    ...(pastBackups && pastBackups.length > 0 ? { pastBackups } : {}),
+  }
+}
+
+function parseTransferSnapshotMetadata(input: Record<string, unknown> | null): TransferSnapshotMetadata | undefined {
+  if (!input) return undefined
+  const kind = stringField(input, 'kind')
+  const senderRaw = stringField(input, 'senderAddress')
+  const receiverRaw = stringField(input, 'receiverAddress')
+  const slotCount = numberField(input, 'slotCount')
+  if (kind !== 'dual-wallet' || !senderRaw || !receiverRaw || !slotCount) return undefined
+  if (!isAddress(senderRaw, { strict: false }) || !isAddress(receiverRaw, { strict: false })) return undefined
+  return {
+    kind: 'dual-wallet',
+    senderAddress: getAddress(senderRaw),
+    receiverAddress: getAddress(receiverRaw),
+    ...(stringField(input, 'receiverHandle') ? { receiverHandle: stringField(input, 'receiverHandle') } : {}),
+    slotCount,
+    ...(stringField(input, 'createdAt') ? { createdAt: stringField(input, 'createdAt') } : {}),
+  }
+}
+
+export function parseEthagentPublicDiscoveryPointer(registration: Record<string, unknown> | null): EthagentPublicDiscoveryPointer | null {
+  if (!registration) return null
+  const ext = objectField(registration, 'x-ethagent') ?? objectField(registration, 'ethagent')
+  const publicSkills = ext ? objectField(ext, 'publicSkills') : null
+  const agentCard = ext ? objectField(ext, 'agentCard') : null
+  const skillsCid = publicSkills ? stringField(publicSkills, 'cid') : undefined
+  const agentCardCid = agentCard ? stringField(agentCard, 'cid') : undefined
+  const updatedAt = (publicSkills ? stringField(publicSkills, 'updatedAt') : undefined)
+    ?? (agentCard ? stringField(agentCard, 'updatedAt') : undefined)
+  if (!skillsCid && !agentCardCid) return null
+  return {
+    ...(skillsCid ? { skillsCid } : {}),
+    ...(agentCardCid ? { agentCardCid } : {}),
+    ...(updatedAt ? { updatedAt } : {}),
+  }
+}
+
+export function parseEthagentOperatorsPointer(registration: Record<string, unknown> | null): EthagentOperatorsPointer | null {
+  if (!registration) return null
+  const ext = objectField(registration, 'x-ethagent') ?? objectField(registration, 'ethagent')
+  const operators = ext ? objectField(ext, 'operators') : null
+  if (!operators) return null
+  const approvedOperatorWallets = parseOperatorRecords(arrayField(operators, 'approvedOperatorWallets') ?? [])
+  const activeRaw = stringField(operators, 'activeOperatorAddress')
+  const ownerRaw = readOwnerAddressField(operators)
+  const ensName = stringField(operators, 'ensName')
+  const restoreAccessEpoch = numberField(operators, 'restoreAccessEpoch')
+  const ownerRestoreAccessKey = parseRestoreAccessKey(objectField(operators, 'ownerRestoreAccessKey'))
+  const activeOperatorAddress = activeRaw && isAddress(activeRaw, { strict: false }) ? getAddress(activeRaw) : undefined
+  const ownerAddress = ownerRaw && isAddress(ownerRaw, { strict: false }) ? getAddress(ownerRaw) : undefined
+  if (approvedOperatorWallets.length === 0 && !activeOperatorAddress && !ownerAddress && !ensName && !ownerRestoreAccessKey && !restoreAccessEpoch) return null
+  return {
+    approvedOperatorWallets,
+    ...(activeOperatorAddress ? { activeOperatorAddress } : {}),
+    ...(ownerAddress ? { ownerAddress } : {}),
+    ...(ensName ? { ensName } : {}),
+    ...(restoreAccessEpoch && Number.isSafeInteger(restoreAccessEpoch) && restoreAccessEpoch > 0 ? { restoreAccessEpoch } : {}),
+    ...(ownerRestoreAccessKey ? { ownerRestoreAccessKey } : {}),
+  }
+}
+
+function parseOperatorRecords(items: unknown[]): ApprovedOperatorWalletRecord[] {
+  const out: ApprovedOperatorWalletRecord[] = []
+  const seen = new Set<string>()
+  for (const item of items) {
+    const record = parseOperatorRecord(item)
+    if (!record) continue
+    const key = record.address.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(record)
+  }
+  return out
+}
+
+function parseOperatorRecord(item: unknown): ApprovedOperatorWalletRecord | null {
+  if (typeof item === 'string') {
+    const trimmed = item.trim()
+    if (!isAddress(trimmed, { strict: false })) return null
+    return { address: getAddress(trimmed) }
+  }
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null
+  const obj = item as Record<string, unknown>
+  const rawAddress = stringField(obj, 'address')
+  if (!rawAddress || !isAddress(rawAddress, { strict: false })) return null
+  const challenge = stringField(obj, 'challenge')
+  const verifiedAt = stringField(obj, 'verifiedAt')
+  const restoreAccessKey = parseRestoreAccessKey(objectField(obj, 'restoreAccessKey'))
+  return {
+    address: getAddress(rawAddress),
+    ...(challenge ? { challenge } : {}),
+    ...(verifiedAt ? { verifiedAt } : {}),
+    ...(restoreAccessKey ? { restoreAccessKey } : {}),
+  }
+}
+
+function parseRestoreAccessKey(obj: Record<string, unknown> | null): WalletContinuityRestoreAccessKey | undefined {
+  if (!obj) return undefined
+  const address = stringField(obj, 'address')
+  const challenge = stringField(obj, 'challenge')
+  const salt = stringField(obj, 'salt')
+  const kemPublicKey = stringField(obj, 'kemPublicKey')
+  const createdAt = stringField(obj, 'createdAt')
+  if (!address || !isAddress(address, { strict: false }) || !challenge || !salt || !kemPublicKey) return undefined
+  return {
+    address: getAddress(address),
+    challenge,
+    salt,
+    kemPublicKey,
+    ...(createdAt ? { createdAt } : {}),
+  }
+}
+
+function serializeRestoreAccessKey(key: WalletContinuityRestoreAccessKey): Record<string, unknown> {
+  return {
+    address: getAddress(key.address),
+    challenge: key.challenge,
+    salt: key.salt,
+    kemPublicKey: key.kemPublicKey,
+    ...(key.createdAt ? { createdAt: key.createdAt } : {}),
+  }
+}
+
+function serializeOperatorsPointer(pointer: EthagentOperatorsPointer): Record<string, unknown> {
+  return {
+    approvedOperatorWallets: pointer.approvedOperatorWallets.map(record => ({
+      address: getAddress(record.address),
+      ...(record.challenge ? { challenge: record.challenge } : {}),
+      ...(record.verifiedAt ? { verifiedAt: record.verifiedAt } : {}),
+      ...(record.restoreAccessKey ? { restoreAccessKey: serializeRestoreAccessKey(record.restoreAccessKey) } : {}),
+    })),
+    ...(pointer.activeOperatorAddress ? { activeOperatorAddress: getAddress(pointer.activeOperatorAddress) } : {}),
+    ...(pointer.ownerAddress ? { ownerAddress: getAddress(pointer.ownerAddress) } : {}),
+    ...(pointer.ensName ? { ensName: pointer.ensName } : {}),
+    ...(pointer.restoreAccessEpoch ? { restoreAccessEpoch: pointer.restoreAccessEpoch } : {}),
+    ...(pointer.ownerRestoreAccessKey ? { ownerRestoreAccessKey: serializeRestoreAccessKey(pointer.ownerRestoreAccessKey) } : {}),
+  }
+}
+
+export function withEthagentBackupPointer(
+  registration: Record<string, unknown> | null,
+  backup: EthagentBackupPointer,
+  publicDiscovery?: EthagentPublicDiscoveryPointer,
+  registrationPointer?: EthagentRegistrationPointer,
+  ownerAddress?: Address,
+): Record<string, unknown> {
+  const inferredOwnerAddress = ownerAddress ?? backup.agentAddress
+  return withEthagentPointers(registration, {
+    backup,
+    publicDiscovery,
+    registration: registrationPointer,
+    ...(inferredOwnerAddress ? { ownerAddress: inferredOwnerAddress } : {}),
+  })
+}
+
+export function withEthagentPointers(
+  registration: Record<string, unknown> | null,
+  pointers: {
+    backup?: EthagentBackupPointer
+    publicDiscovery?: EthagentPublicDiscoveryPointer
+    registration?: EthagentRegistrationPointer
+    ensName?: string
+    operators?: EthagentOperatorsPointer
+    ownerAddress?: Address
+  },
+): Record<string, unknown> {
+  const next: Record<string, unknown> = registration ? { ...registration } : {}
+  const prior = objectField(next, 'x-ethagent') ?? {}
+  const { backup, publicDiscovery, registration: registrationPointer, operators } = pointers
+  const updatedAt = publicDiscovery?.updatedAt ?? backup?.createdAt
+  const ownerAddress = pointers.ownerAddress
+    ? getAddress(pointers.ownerAddress)
+    : backup?.agentAddress
+      ? getAddress(backup.agentAddress)
+      : undefined
+  const priorX402 = objectField(prior, 'x402') ?? {}
+  const ext: Record<string, unknown> = {
+    ...prior,
+    version: 1,
+    ...(ownerAddress ? {
+      agentAddress: ownerAddress,
+      x402: {
+        ...priorX402,
+        walletAddress: ownerAddress,
+      },
+    } : {}),
+    ...(backup ? {
+      backup: {
+        cid: backup.cid,
+        ...(backup.envelopeVersion ? { envelopeVersion: backup.envelopeVersion } : {}),
+        ...(backup.createdAt ? { createdAt: backup.createdAt } : {}),
+        ...(backup.transferSnapshot ? { transferSnapshot: serializeTransferSnapshotMetadata(backup.transferSnapshot) } : {}),
+      },
+    } : {}),
+    ...(publicDiscovery?.skillsCid ? {
+      publicSkills: {
+        cid: publicDiscovery.skillsCid,
+        format: 'application/json',
+        ...(updatedAt ? { updatedAt } : {}),
+      },
+    } : {}),
+    ...(publicDiscovery?.agentCardCid ? {
+      agentCard: {
+        cid: publicDiscovery.agentCardCid,
+        format: 'application/json',
+        ...(updatedAt ? { updatedAt } : {}),
+      },
+    } : {}),
+    ...(operators ? { operators: serializeOperatorsPointer(operators) } : {}),
+  }
+  delete ext.transfer
+  delete ext.handoff
+  next['x-ethagent'] = ext
+  if (publicDiscovery) {
+    next.services = withPublicDiscoveryServices(next.services, publicDiscovery, pointers.ensName)
+  }
+  if (registrationPointer && registrationPointer.agentId !== undefined) {
+    next.registrations = withRegistrationsArray(next.registrations, registrationPointer)
+  }
+  return next
+}
+
+function serializeTransferSnapshotMetadata(metadata: TransferSnapshotMetadata): Record<string, unknown> {
+  return {
+    kind: 'dual-wallet',
+    senderAddress: getAddress(metadata.senderAddress),
+    receiverAddress: getAddress(metadata.receiverAddress),
+    ...(metadata.receiverHandle ? { receiverHandle: metadata.receiverHandle } : {}),
+    slotCount: metadata.slotCount,
+    ...(metadata.createdAt ? { createdAt: metadata.createdAt } : {}),
+  }
+}
+
+function withPublicDiscoveryServices(input: unknown, publicDiscovery: EthagentPublicDiscoveryPointer, ensName?: string): unknown[] {
+  const prior = Array.isArray(input) ? input.filter(item => item && typeof item === 'object') : []
+  const services = prior.filter(item => !isEthagentManagedService(item)) as unknown[]
+  if (publicDiscovery.agentCardCid) {
+    const endpoint = `ipfs://${publicDiscovery.agentCardCid}`
+    pushUniqueService(services, {
+      type: 'a2a',
+      name: 'agent-card',
+      endpoint,
+      url: endpoint,
+    })
+  }
+  if (publicDiscovery.skillsCid) {
+    const endpoint = `ipfs://${publicDiscovery.skillsCid}`
+    pushUniqueService(services, {
+      type: 'A2A-skills',
+      name: 'public-skills',
+      endpoint,
+      url: endpoint,
+    })
+  }
+  if (ensName) {
+    services.push({ name: 'ENS', endpoint: ensName, version: 'v1' })
+  }
+  return services
+}
+
+function pushUniqueService(services: unknown[], service: Record<string, string>): void {
+  const duplicate = services.some(item => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return false
+    const obj = item as Record<string, unknown>
+    return obj.type === service.type && obj.endpoint === service.endpoint
+  })
+  if (!duplicate) services.push(service)
+}
+
+function isEthagentManagedService(item: unknown): boolean {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return false
+  const obj = item as Record<string, unknown>
+  const type = obj.type
+  const name = obj.name
+  if (name === 'ENS') return true
+  if (type === 'a2a' && (name === undefined || name === 'agent-card')) return true
+  return (type === 'A2A-skills' || type === 'ipfs') && name === 'public-skills'
+}
+
+function withRegistrationsArray(_input: unknown, registration: EthagentRegistrationPointer): unknown[] {
+  return [{
+    agentId: registrationAgentIdValue(registration.agentId),
+    agentRegistry: `eip155:${registration.chainId}:${registration.identityRegistryAddress}`,
+  }]
+}
+
+function registrationAgentIdValue(agentId: string | number | undefined): string | number | undefined {
+  if (typeof agentId === 'number') return agentId
+  if (typeof agentId !== 'string') return agentId
+  const trimmed = agentId.trim()
+  if (!/^(0|[1-9]\d*)$/.test(trimmed)) return agentId
+  const numeric = Number(trimmed)
+  return Number.isSafeInteger(numeric) ? numeric : agentId
+}

package/src/identity/registry/erc8004/ownership.ts

@@ -0,0 +1,121 @@
+import { getAddress, type Address, type PublicClient } from 'viem'
+import { OPERATOR_VAULT_ABI } from '../operatorVault.js'
+import { ERC8004_ABI } from './abi.js'
+import { createErc8004PublicClient } from './client.js'
+import type { Erc8004RegistryConfig } from './types.js'
+
+type TokenOwnerReadClient = Pick<PublicClient, 'readContract'>
+
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'
+
+async function readErc8004TokenOwner(args: Erc8004RegistryConfig & {
+  agentId: bigint
+  publicClient?: TokenOwnerReadClient
+}): Promise<Address> {
+  const publicClient = args.publicClient ?? createErc8004PublicClient(args)
+  const owner = await publicClient.readContract({
+    address: args.identityRegistryAddress,
+    abi: ERC8004_ABI,
+    functionName: 'ownerOf',
+    args: [args.agentId],
+  }) as Address
+  return getAddress(owner)
+}
+
+export type Erc8004TokenOwnerValidation =
+  | { ok: true; ownerAddress: Address }
+  | { ok: false; reason: 'token-owner-mismatch' | 'token-owner-lookup-failed'; ownerAddress?: Address; detail: string }
+
+export async function validateErc8004TokenOwner(args: Erc8004RegistryConfig & {
+  agentId: bigint
+  expectedOwner: Address
+  publicClient?: TokenOwnerReadClient
+  operatorVaults?: Readonly<Record<string, string>>
+}): Promise<Erc8004TokenOwnerValidation> {
+  let owner: Address
+  try {
+    owner = await readErc8004TokenOwner(args)
+  } catch (err: unknown) {
+    return {
+      ok: false,
+      reason: 'token-owner-lookup-failed',
+      detail: err instanceof Error ? err.message : String(err),
+    }
+  }
+  const expectedOwner = getAddress(args.expectedOwner)
+  if (owner.toLowerCase() === expectedOwner.toLowerCase()) {
+    return { ok: true, ownerAddress: owner }
+  }
+  const vaultOwnerResult = await readVaultLevelOwner({
+    ...args,
+    vaultAddress: owner,
+  })
+  if (vaultOwnerResult.kind === 'empty') {
+    return {
+      ok: false,
+      reason: 'token-owner-lookup-failed',
+      detail: `ERC-8004 token #${args.agentId.toString()} is still reported at the operator delegation vault, but that vault record is empty. Ownership is still settling; retry shortly.`,
+    }
+  }
+  if (vaultOwnerResult.kind === 'error') {
+    return {
+      ok: false,
+      reason: 'token-owner-lookup-failed',
+      detail: vaultOwnerResult.error instanceof Error ? vaultOwnerResult.error.message : String(vaultOwnerResult.error),
+    }
+  }
+  if (vaultOwnerResult.kind === 'ok') {
+    const vaultOwner = vaultOwnerResult.ownerAddress
+    if (vaultOwner.toLowerCase() === expectedOwner.toLowerCase()) {
+      return { ok: true, ownerAddress: vaultOwner }
+    }
+    return {
+      ok: false,
+      reason: 'token-owner-mismatch',
+      ownerAddress: vaultOwner,
+      detail: `ERC-8004 token #${args.agentId.toString()} is held by the operator delegation vault for ${vaultOwner}`,
+    }
+  }
+  return {
+    ok: false,
+    reason: 'token-owner-mismatch',
+    ownerAddress: owner,
+    detail: `ERC-8004 token #${args.agentId.toString()} is owned by ${shortHex(owner)}`,
+  }
+}
+
+async function readVaultLevelOwner(args: Erc8004RegistryConfig & {
+  agentId: bigint
+  vaultAddress: Address
+  publicClient?: TokenOwnerReadClient
+}): Promise<
+  | { kind: 'ok'; ownerAddress: Address }
+  | { kind: 'empty' }
+  | { kind: 'not-vault' }
+  | { kind: 'error'; error: unknown }
+> {
+  try {
+    const client = args.publicClient ?? createErc8004PublicClient(args)
+    const vaultOwner = await client.readContract({
+      address: args.vaultAddress,
+      abi: OPERATOR_VAULT_ABI,
+      functionName: 'agentOwner',
+      args: [args.identityRegistryAddress, args.agentId],
+    }) as Address
+    const normalizedVaultOwner = getAddress(vaultOwner)
+    if (normalizedVaultOwner.toLowerCase() === ZERO_ADDRESS) return { kind: 'empty' }
+    return { kind: 'ok', ownerAddress: normalizedVaultOwner }
+  } catch (err: unknown) {
+    return looksLikeTransientVaultReadFailure(err) ? { kind: 'error', error: err } : { kind: 'not-vault' }
+  }
+}
+
+function looksLikeTransientVaultReadFailure(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err)
+  return /timeout|network|header not found|rate|server|rpc/i.test(message)
+}
+
+function shortHex(value: string): string {
+  if (value.length <= 14) return value
+  return `${value.slice(0, 6)}...${value.slice(-4)}`
+}

package/src/identity/registry/erc8004/preflight.ts

@@ -0,0 +1,123 @@
+import type { Address, Hex } from 'viem'
+import type { Erc8004RegistryConfig } from './types.js'
+import { createErc8004PublicClient } from './client.js'
+import { encodeRegisterAgent, encodeSetAgentUri } from './transactions.js'
+import { cleanRpcError, formatEthAmount } from './utils.js'
+
+export type RegisterAgentPreflight = {
+  gas: bigint
+  gasPrice: bigint
+  estimatedCostWei: bigint
+  requiredBalanceWei: bigint
+  balanceWei: bigint
+}
+
+export type RegisterAgentPreflightErrorCode = 'insufficient-funds' | 'simulation-failed'
+
+export class RegisterAgentPreflightError extends Error {
+  code: RegisterAgentPreflightErrorCode
+  title: string
+  detail: string
+  hint: string
+  requiredBalanceWei?: bigint
+  balanceWei?: bigint
+
+  constructor(args: {
+    code: RegisterAgentPreflightErrorCode
+    title: string
+    detail: string
+    hint: string
+    requiredBalanceWei?: bigint
+    balanceWei?: bigint
+  }) {
+    super(args.detail ? `${args.title}: ${args.detail}` : args.title)
+    this.name = 'RegisterAgentPreflightError'
+    this.code = args.code
+    this.title = args.title
+    this.detail = args.detail
+    this.hint = args.hint
+    this.requiredBalanceWei = args.requiredBalanceWei
+    this.balanceWei = args.balanceWei
+  }
+}
+
+type RegisterAgentPreflightClient = {
+  estimateGas: (args: { account: Address; to: Address; data: Hex }) => Promise<bigint>
+  getGasPrice: () => Promise<bigint>
+  getBalance: (args: { address: Address }) => Promise<bigint>
+}
+
+export async function preflightRegisterAgent(args: Erc8004RegistryConfig & {
+  ownerAddress: Address
+  agentURI: string
+  publicClient?: RegisterAgentPreflightClient
+}): Promise<RegisterAgentPreflight> {
+  const publicClient = args.publicClient ?? createErc8004PublicClient(args) as RegisterAgentPreflightClient
+  const data = encodeRegisterAgent({ agentURI: args.agentURI })
+  let gas: bigint
+  try {
+    gas = await publicClient.estimateGas({
+      account: args.ownerAddress,
+      to: args.identityRegistryAddress,
+      data,
+    })
+  } catch (err: unknown) {
+    throw new RegisterAgentPreflightError({
+      code: 'simulation-failed',
+      title: 'Registration Blocked',
+      detail: cleanRpcError(err),
+      hint: 'No transaction was sent.',
+    })
+  }
+  const [gasPrice, balance] = await Promise.all([
+    publicClient.getGasPrice(),
+    publicClient.getBalance({ address: args.ownerAddress }),
+  ])
+  const estimatedCost = gas * gasPrice
+  const requiredBalance = estimatedCost + estimatedCost / 5n
+  if (balance < requiredBalance) {
+    throw new RegisterAgentPreflightError({
+      code: 'insufficient-funds',
+      title: 'Not Enough ETH',
+      detail: `Need ~${formatEthAmount(requiredBalance)} ETH. Wallet has ${formatEthAmount(balance)} ETH.`,
+      hint: 'Add ETH to this wallet, then try again.',
+      requiredBalanceWei: requiredBalance,
+      balanceWei: balance,
+    })
+  }
+  return {
+    gas,
+    gasPrice,
+    estimatedCostWei: estimatedCost,
+    requiredBalanceWei: requiredBalance,
+    balanceWei: balance,
+  }
+}
+
+export async function preflightSetAgentUri(args: Erc8004RegistryConfig & {
+  account: Address
+  agentId: bigint
+  newUri: string
+  publicClient?: RegisterAgentPreflightClient
+}): Promise<void> {
+  const publicClient = args.publicClient ?? createErc8004PublicClient(args) as RegisterAgentPreflightClient
+  const data = encodeSetAgentUri({ agentId: args.agentId, newUri: args.newUri })
+  try {
+    await publicClient.estimateGas({
+      account: args.account,
+      to: args.identityRegistryAddress,
+      data,
+    })
+  } catch (err: unknown) {
+    const detail = cleanRpcError(err)
+    const looksLikeOwnershipRevert = /not.*owner|owner.*only|unauthor|forbidden|caller/i.test(detail)
+    throw new RegisterAgentPreflightError({
+      code: 'simulation-failed',
+      title: 'Backup Update Blocked',
+      detail,
+      hint: looksLikeOwnershipRevert
+        ? `Connect the wallet that owns this agent (${args.account}) and try again.`
+        : 'No transaction was sent.',
+    })
+  }
+}

package/src/identity/registry/erc8004/transactions.ts

@@ -0,0 +1,77 @@
+import { decodeEventLog, encodeFunctionData, getAddress, type Address, type Hex } from 'viem'
+import { ERC8004_ABI, REGISTERED_EVENT, TRANSFER_EVENT } from './abi.js'
+
+type ReceiptLog = { address?: Address; topics: readonly Hex[]; data: Hex }
+
+export function encodeRegisterAgent(args: {
+  agentURI: string
+}): Hex {
+  return encodeFunctionData({
+    abi: ERC8004_ABI,
+    functionName: 'register',
+    args: [args.agentURI],
+  })
+}
+
+export function encodeSetAgentUri(args: {
+  agentId: bigint
+  newUri: string
+}): Hex {
+  return encodeFunctionData({
+    abi: ERC8004_ABI,
+    functionName: 'setAgentURI',
+    args: [args.agentId, args.newUri],
+  })
+}
+
+export function registeredAgentFromReceipt(args: {
+  logs: ReceiptLog[]
+  identityRegistryAddress: Address
+  ownerAddress?: Address
+  fallbackAgentURI?: string
+}): { agentId: bigint; agentURI: string; owner: Address } {
+  for (const log of args.logs) {
+    if (log.address && log.address.toLowerCase() !== args.identityRegistryAddress.toLowerCase()) continue
+    try {
+      const decoded = decodeEventLog({
+        abi: [REGISTERED_EVENT],
+        topics: log.topics as [Hex, ...Hex[]],
+        data: log.data,
+      })
+      if (decoded.eventName !== 'Registered') continue
+      const eventArgs = decoded.args as { agentId?: bigint; agentURI?: string; owner?: Address }
+      if (eventArgs.agentId === undefined || !eventArgs.agentURI || !eventArgs.owner) continue
+      if (args.ownerAddress && eventArgs.owner.toLowerCase() !== args.ownerAddress.toLowerCase()) continue
+      return {
+        agentId: eventArgs.agentId,
+        agentURI: eventArgs.agentURI,
+        owner: getAddress(eventArgs.owner),
+      }
+    } catch {
+    }
+  }
+  const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'
+  for (const log of args.logs) {
+    if (log.address && log.address.toLowerCase() !== args.identityRegistryAddress.toLowerCase()) continue
+    try {
+      const decoded = decodeEventLog({
+        abi: [TRANSFER_EVENT],
+        topics: log.topics as [Hex, ...Hex[]],
+        data: log.data,
+      })
+      if (decoded.eventName !== 'Transfer') continue
+      const eventArgs = decoded.args as { from?: Address; to?: Address; tokenId?: bigint }
+      if (!eventArgs.from || !eventArgs.to || eventArgs.tokenId === undefined) continue
+      if (eventArgs.from.toLowerCase() !== ZERO_ADDRESS) continue
+      if (args.ownerAddress && eventArgs.to.toLowerCase() !== args.ownerAddress.toLowerCase()) continue
+      const agentURI = args.fallbackAgentURI ?? ''
+      return {
+        agentId: eventArgs.tokenId,
+        agentURI,
+        owner: getAddress(eventArgs.to),
+      }
+    } catch {
+    }
+  }
+  throw new Error('ERC-8004 registration event was not found in transaction receipt')
+}