ethagent 1.1.2 → 2.0.0

package/src/identity/hub/flows/custody/CustodyEditFlow.tsx

@@ -0,0 +1,347 @@
+import React from 'react'
+import type { Address } from 'viem'
+import { Box, Text } from 'ink'
+import { Surface } from '../../../../ui/Surface.js'
+import { Select } from '../../../../ui/Select.js'
+import { theme } from '../../../../ui/theme.js'
+import type { ProfileUpdates, Step } from '../../identityHubReducer.js'
+import {
+  displayCustodyMode,
+  identityOwnerAddress,
+  readCustodyMode,
+  readIdentityStateString,
+} from '../../model/custody.js'
+import { ensValidationReasonText, selectEnsStatus } from '../../model/ens.js'
+import { shortAddress } from '../../model/format.js'
+import { lastBackupLabel } from '../../model/identity.js'
+import {
+  describeFixPlanItem,
+  fixPlanRequiresOwnerWallet,
+  reconcileWalletSetup,
+  type AgentReconciliation,
+  type RecordsFixPlan,
+} from '../../reconciliation/index.js'
+
+const footerHint = (hint: string) => <Text color={theme.dim}>{hint}</Text>
+
+type CustodyStep = Extract<Step, { kind: 'custody-model' | 'custody-advanced-confirm' | 'custody-simple-confirm' }>
+
+interface CustodyEditFlowProps {
+  step: CustodyStep
+  reconciliation?: AgentReconciliation
+  vaultAddress?: Address
+  onSetStep: (step: Step) => void
+  onSwitchToAdvanced: (returnTo: Step, profileUpdates: ProfileUpdates) => void
+  onSwitchToSimple: (returnTo: Step, profileUpdates: ProfileUpdates) => void
+  onWithdrawToken: (returnTo: Step) => void
+  onReturnToVault: (returnTo: Step, vaultAddress: Address) => void
+  onResumeAdvanced: (returnTo: Step) => void
+  onManageOperatorWallets: () => void
+  onFixRecords: (plan: RecordsFixPlan) => void
+  onPrepareTransfer: () => void
+  onBack: () => void
+}
+
+export function isCustodyEditStep(step: Step): step is CustodyStep {
+  return step.kind === 'custody-model'
+    || step.kind === 'custody-advanced-confirm'
+    || step.kind === 'custody-simple-confirm'
+}
+
+export const CustodyEditFlow: React.FC<CustodyEditFlowProps> = ({
+  step,
+  reconciliation,
+  vaultAddress,
+  onSetStep,
+  onSwitchToAdvanced,
+  onSwitchToSimple,
+  onWithdrawToken,
+  onReturnToVault,
+  onResumeAdvanced,
+  onManageOperatorWallets,
+  onFixRecords,
+  onPrepareTransfer,
+  onBack,
+}) => {
+  const identity = step.identity
+  const registry = step.registry
+  const returnTo = step.returnTo
+  const state = (identity.state ?? {}) as Record<string, unknown>
+  const custodyMode = readCustodyMode(state)
+  const ownerAddress = identityOwnerAddress(identity, reconciliation?.onChainOwner)
+  const activeOperator = readIdentityStateString(state, 'activeOperatorAddress')
+  const approvedOperatorCount = Array.isArray(state.approvedOperatorWallets)
+    ? (state.approvedOperatorWallets as unknown[]).length
+    : 0
+  const agentName = readIdentityStateString(state, 'name')
+  const tokenLabel = identity.agentId ? `Token #${identity.agentId}` : 'Token #unknown'
+  const tokenOwner = identity.ownerAddress ?? identity.address
+
+  const [fixPlan, setFixPlan] = React.useState<RecordsFixPlan | null>(null)
+  React.useEffect(() => {
+    if (step.kind !== 'custody-model') return
+    if (custodyMode !== 'advanced') return
+    let cancelled = false
+    reconcileWalletSetup({ identity, registry })
+      .then(plan => { if (!cancelled) setFixPlan(plan) })
+      .catch(() => { if (!cancelled) setFixPlan(null) })
+    return () => { cancelled = true }
+  }, [identity, registry, step.kind, custodyMode])
+
+  if (step.kind === 'custody-model') {
+    type Action = 'switch-advanced' | 'switch-simple' | 'resume-advanced' | 'cancel-advanced' | 'withdraw-token' | 'return-to-vault' | 'manage-operator-wallets' | 'fix-records' | 'back'
+    const onChainCustody = reconciliation?.custody
+    const midFlow = onChainCustody === 'mid-flow-uri-pending'
+    const isAdvanced = onChainCustody === 'advanced' || midFlow || custodyMode === 'advanced'
+    const vaultHolds = onChainCustody === 'advanced' || midFlow
+    const subtitle = midFlow
+      ? 'Advanced setup pending. This agent vault holds your token. Finish by publishing the first onchain update.'
+      : isAdvanced
+        ? 'Advanced is active. Authorized operator wallets publish updates for this agent without an owner signature each time.'
+        : 'Simple is active. One wallet owns the token and signs every update.'
+    const modeLabel = midFlow ? 'Advanced (setup pending)' : displayCustodyMode(isAdvanced ? 'advanced' : 'simple')
+    const options: Array<{ value: Action; role?: 'section' | 'utility'; label: string; hint?: string }> = []
+    if (midFlow) {
+      options.push({ value: 'resume-advanced', role: 'section', label: 'Resume Setup' })
+      options.push({
+        value: 'resume-advanced',
+        label: 'Resume Advanced Setup',
+        hint: 'Sign once to publish onchain and finish the agent-vault switch.',
+      })
+      options.push({
+        value: 'cancel-advanced',
+        label: 'Cancel Advanced Setup',
+        hint: 'Unwrap the token back to the owner wallet and revert to simple.',
+      })
+    }
+    options.push({ value: 'switch-advanced', role: 'section', label: 'Custody' })
+    if (!isAdvanced) {
+      options.push({
+        value: 'switch-advanced',
+        label: 'Switch to Advanced',
+        hint: 'Deposit this token into its own OperatorVault so operator wallets can publish updates onchain.',
+      })
+    } else {
+      if (!midFlow) {
+        options.push({
+          value: 'switch-simple',
+          label: 'Switch to Simple',
+          hint: 'Unwrap the token and revoke operator delegations.',
+        })
+      }
+      if (vaultHolds) {
+        options.push({
+          value: 'withdraw-token',
+          label: 'Withdraw Token',
+          hint: 'Unwrap this token to the owner wallet. Vault setup stays for easy redeposit.',
+        })
+      } else if (vaultAddress) {
+        options.push({
+          value: 'return-to-vault',
+          label: 'Return Token to Vault',
+          hint: 'Redeposit this token to its agent vault. No redeploy, no operator re-add.',
+        })
+      }
+      options.push({ value: 'manage-operator-wallets', role: 'section', label: 'Operators' })
+      options.push({
+        value: 'manage-operator-wallets',
+        label: 'Manage Operators',
+        hint: 'Add or revoke wallets that can publish updates onchain.',
+      })
+    }
+    const hasFixablePlan = fixPlan !== null && fixPlanRequiresOwnerWallet(fixPlan)
+    if (hasFixablePlan) {
+      options.push({ value: 'fix-records', role: 'section', label: 'Records Out Of Sync' })
+      options.push({
+        value: 'fix-records',
+        label: 'Fix Records (Owner Wallet)',
+        hint: 'Sync ENS resolver approvals with the operator wallet list.',
+      })
+    }
+    options.push({ value: 'back', role: 'section', label: 'Navigation' })
+    options.push({ value: 'back', label: 'Back', hint: 'Return to Identity Hub', role: 'utility' })
+    const notice = step.kind === 'custody-model' ? step.notice : undefined
+    return (
+      <Surface title="Custody Mode" subtitle={subtitle} footer={footerHint('enter select · esc back')}>
+        {notice ? (
+          <Box marginBottom={1}>
+            <Text color={theme.accentPeriwinkle}>{notice}</Text>
+          </Box>
+        ) : null}
+        <Box flexDirection="column">
+          {(() => {
+            const ensStatus = selectEnsStatus(identity)
+            return (
+              <Text>
+                <Text color={theme.dim}>{'ENS'.padEnd(14)}</Text>
+                {ensStatus.kind === 'linked'
+                  ? <Text color={theme.accentPeriwinkle}>{ensStatus.name}</Text>
+                  : ensStatus.kind === 'issue'
+                    ? <Text color={theme.accentError}>{ensStatus.name} ({ensValidationReasonText(ensStatus.reason)})</Text>
+                    : <Text color={theme.dim}>Not Linked</Text>}
+              </Text>
+            )
+          })()}
+          <Row label="Custody" value={modeLabel} />
+          <Row label="Owner" value={shortAddress(ownerAddress || tokenOwner)} />
+          {isAdvanced && vaultAddress ? <Row label="Agent Vault" value={shortAddress(vaultAddress)} /> : null}
+          {isAdvanced ? (
+            <Row
+              label="Operators"
+              value={approvedOperatorCount > 1
+                ? `${approvedOperatorCount} authorized${activeOperator ? ` (active ${shortAddress(activeOperator)})` : ''}`
+                : activeOperator
+                  ? shortAddress(activeOperator)
+                  : 'None Authorized'}
+              muted={!activeOperator && approvedOperatorCount === 0}
+            />
+          ) : null}
+          {(() => {
+            const lastBackup = lastBackupLabel(identity)
+            return <Row label="Last Saved" value={lastBackup} muted={lastBackup === 'never'} />
+          })()}
+        </Box>
+        {fixPlan && fixPlan.items.length > 0 ? (
+          <Box marginTop={1} flexDirection="column">
+            <Text color={theme.accentPeriwinkle} bold>Records out of sync:</Text>
+            {fixPlan.items.map((item, idx) => (
+              <Text key={idx} color={theme.dim}>· {describeFixPlanItem(item)}</Text>
+            ))}
+          </Box>
+        ) : null}
+        <Box marginTop={1}>
+          <Select<Action>
+            options={options}
+            hintLayout="inline"
+            onSubmit={choice => {
+              if (choice === 'back') return onBack()
+              if (choice === 'manage-operator-wallets') return onManageOperatorWallets()
+              if (choice === 'withdraw-token') return onWithdrawToken(returnTo ?? { kind: 'menu' })
+              if (choice === 'return-to-vault') {
+                if (!vaultAddress) return
+                return onReturnToVault(returnTo ?? { kind: 'menu' }, vaultAddress)
+              }
+              if (choice === 'resume-advanced') return onResumeAdvanced(returnTo ?? { kind: 'menu' })
+              if (choice === 'cancel-advanced') {
+                onSetStep({ kind: 'custody-simple-confirm', identity, registry, returnTo })
+                return
+              }
+              if (choice === 'fix-records') {
+                if (fixPlan) onFixRecords(fixPlan)
+                return
+              }
+              if (choice === 'switch-advanced') {
+                onSetStep({ kind: 'custody-advanced-confirm', identity, registry, returnTo })
+                return
+              }
+              if (choice === 'switch-simple') {
+                onSetStep({ kind: 'custody-simple-confirm', identity, registry, returnTo })
+                return
+              }
+            }}
+            onCancel={onBack}
+          />
+        </Box>
+      </Surface>
+    )
+  }
+
+  if (step.kind === 'custody-advanced-confirm') {
+    type Action = 'confirm' | 'transfer' | 'back'
+    return (
+      <Surface
+        title="Switch to Advanced"
+        subtitle="Move this token into its own OperatorVault so authorized operator wallets can update this agent onchain without your signature each time."
+        footer={footerHint('enter confirm, esc back')}
+      >
+        <Box flexDirection="column">
+          <Row label="Token" value={tokenLabel} />
+          {agentName ? <Row label="Name" value={agentName} /> : null}
+          <Row label="Owner Wallet" value={shortAddress(ownerAddress || tokenOwner)} />
+          <Text color={theme.textSubtle}>You sign once now to deposit token #{identity.agentId ?? 'unknown'} into a dedicated OperatorVault.</Text>
+          <Text color={theme.textSubtle}>This vault can hold only this ERC-8004 token.</Text>
+          <Text color={theme.textSubtle}>Other agent tokens use their own vaults.</Text>
+          <Text color={theme.textSubtle}>After that, operator wallets you authorize can publish updates for this agent.</Text>
+          <Box marginTop={1} flexDirection="column">
+            <Text color={theme.accentBlue}>Want a different wallet to be the owner?</Text>
+            <Text color={theme.textSubtle}>Move the token there first via Prepare Token Transfer; your continuity files come along.</Text>
+          </Box>
+        </Box>
+        <Box marginTop={1}>
+          <Select<Action>
+            options={[
+              { value: 'confirm', role: 'section', label: 'Confirm' },
+              { value: 'confirm', label: 'Yes, Switch to Advanced', hint: `Sign with ${shortAddress(ownerAddress || tokenOwner)} to deposit this token into its agent vault` },
+              { value: 'transfer', role: 'section', label: 'Move Token First' },
+              { value: 'transfer', label: 'Prepare Token Transfer', hint: 'Move the token to a different wallet first, with snapshot handoff' },
+              { value: 'back', role: 'section', label: 'Cancel' },
+              { value: 'back', label: 'No, Go Back', hint: 'Return without changing custody', role: 'utility' },
+            ]}
+            hintLayout="inline"
+            onSubmit={choice => {
+              if (choice === 'back') return onBack()
+              if (choice === 'transfer') return onPrepareTransfer()
+              const updates: ProfileUpdates = {
+                custodyMode: 'advanced',
+                ownerAddress: ownerAddress || tokenOwner,
+                bumpRestoreAccessEpoch: true,
+                custodyPhase: 'switch-advanced',
+              }
+              onSwitchToAdvanced(returnTo ?? { kind: 'menu' }, updates)
+            }}
+            onCancel={onBack}
+          />
+        </Box>
+      </Surface>
+    )
+  }
+
+  type Action = 'confirm' | 'back'
+  return (
+    <Surface
+      title="Switch to Simple"
+      subtitle="Unwraps this ERC-8004 token from its agent vault and returns it directly to the owner wallet."
+      footer={footerHint('enter confirm · esc back')}
+    >
+      <Box flexDirection="column">
+        <Row label="Token" value={tokenLabel} />
+        {agentName ? <Row label="Name" value={agentName} /> : null}
+        <Text> </Text>
+        <Text color={theme.accentBlue}>Operators lose decrypt access on future snapshots immediately.</Text>
+        <Text color={theme.textSubtle}>Operator approvals are cleared from local state for future snapshots. Revoke onchain via Manage Operators first if needed.</Text>
+        <Text color={theme.textSubtle}>This switch calls the agent vault's unwrap function for this token, so the owner wallet must sign the transaction.</Text>
+      </Box>
+      <Box marginTop={1}>
+        <Select<Action>
+          options={[
+            { value: 'confirm', role: 'section', label: 'Confirm' },
+            { value: 'confirm', label: 'Yes, Switch to Simple', hint: `Sign with the owner wallet to unwrap ${tokenLabel} from its agent vault` },
+            { value: 'back', role: 'section', label: 'Cancel' },
+            { value: 'back', label: 'No, Go Back', hint: 'Return without changing custody', role: 'utility' },
+          ]}
+          hintLayout="inline"
+          onSubmit={choice => {
+            if (choice === 'back') return onBack()
+            const updates: ProfileUpdates = {
+              custodyMode: 'simple',
+              bumpRestoreAccessEpoch: true,
+              custodyPhase: 'switch-simple',
+              approvedOperatorWallets: [],
+              activeOperatorAddress: '',
+              operatorVaultAddress: '',
+            }
+            onSwitchToSimple(returnTo ?? { kind: 'menu' }, updates)
+          }}
+          onCancel={onBack}
+        />
+      </Box>
+    </Surface>
+  )
+}
+
+const Row: React.FC<{ label: string; value: string; muted?: boolean }> = ({ label, value, muted }) => (
+  <Text>
+    <Text color={theme.dim}>{label.padEnd(14)}</Text>
+    <Text color={muted ? theme.dim : theme.text}>{value}</Text>
+  </Text>
+)

package/src/identity/hub/flows/custody/custodyEffects.ts

@@ -0,0 +1,321 @@
+import { encodeDeployData, getAddress, type Address, type Hex, type PublicClient } from 'viem'
+import {
+  confirmAgentWithdrawnFromVault,
+  encodeDepositAgent,
+  encodeUnwrapAgent,
+  isAgentInVault,
+  resolveConfiguredOperatorVaultAddress,
+  OPERATOR_VAULT_ABI,
+  OPERATOR_VAULT_DEPLOY_BYTECODE,
+  assertVaultBytecode,
+} from '../../../registry/operatorVault.js'
+import {
+  createErc8004PublicClient,
+  type Erc8004RegistryConfig,
+} from '../../../registry/erc8004.js'
+import type { EthagentIdentity } from '../../../../storage/config.js'
+import { readOperatorVaultAddressField, readOwnerAddressField } from '../../../identityCompat.js'
+import { prepareTransactionGasFee, sendBrowserWalletTransaction } from '../../../wallet/browserWallet.js'
+import { acquireTxGuard, releaseTxGuard, type TxGuardKind } from '../../txGuard.js'
+import { awaitConfirmedReceipt } from '../../effects/receipts.js'
+import type { EffectCallbacks } from '../../effects/types.js'
+import { readCustodyMode } from '../../model/custody.js'
+
+export function resolveOperatorVaultAddress(
+  identity: EthagentIdentity,
+  operatorVaults?: Readonly<Record<string, string>>,
+): Address | undefined {
+  const identityVault = readOperatorVaultAddressField(identity.state as Record<string, unknown> | undefined)
+  if (identityVault) return getAddress(identityVault)
+  if (readCustodyMode(identity.state as Record<string, unknown> | undefined) !== 'advanced') return undefined
+  if (!identity.chainId) return undefined
+  return resolveConfiguredOperatorVaultAddress(operatorVaults, identity.chainId)
+}
+
+async function withTxGuard<T>(kind: TxGuardKind, fn: () => Promise<T>): Promise<T> {
+  acquireTxGuard(kind)
+  try {
+    return await fn()
+  } finally {
+    releaseTxGuard(kind)
+  }
+}
+
+export async function runVaultDeployTransaction(args: {
+  registry: Erc8004RegistryConfig
+  walletAddress: Address
+  agentId: bigint
+  callbacks: EffectCallbacks
+  publicClient?: Pick<PublicClient, 'waitForTransactionReceipt' | 'getBytecode'>
+  flowId?: string
+}): Promise<{ txHash: Hex; vaultAddress: Address }> {
+  return withTxGuard('vault-deploy', () => runVaultDeployTransactionInner(args))
+}
+
+async function runVaultDeployTransactionInner(args: {
+  registry: Erc8004RegistryConfig
+  walletAddress: Address
+  agentId: bigint
+  callbacks: EffectCallbacks
+  publicClient?: Pick<PublicClient, 'waitForTransactionReceipt' | 'getBytecode'>
+  flowId?: string
+}): Promise<{ txHash: Hex; vaultAddress: Address }> {
+  const walletAddress = getAddress(args.walletAddress)
+  const registryAddress = getAddress(args.registry.identityRegistryAddress)
+  const deployData = encodeDeployData({
+    abi: OPERATOR_VAULT_ABI,
+    bytecode: OPERATOR_VAULT_DEPLOY_BYTECODE,
+    args: [registryAddress, args.agentId],
+  })
+  const gasFeeClient = createErc8004PublicClient(args.registry)
+  const gasFee = await prepareTransactionGasFee({
+    client: gasFeeClient,
+    account: walletAddress,
+    data: deployData,
+  })
+  const result = await sendBrowserWalletTransaction({
+    chainId: args.registry.chainId,
+    expectedAccount: walletAddress,
+    data: deployData,
+    gas: gasFee.gas,
+    maxFeePerGas: gasFee.maxFeePerGas,
+    maxPriorityFeePerGas: gasFee.maxPriorityFeePerGas,
+    purpose: 'deploy-agent-vault',
+    onReady: args.callbacks.onWalletReady,
+    ...(args.flowId ? { flowId: args.flowId } : {}),
+  })
+  args.callbacks.onWalletReady(null)
+  const client = args.publicClient ?? createErc8004PublicClient(args.registry)
+  const receipt = await awaitConfirmedReceipt(client, result.txHash, 'Operator delegation vault deploy', { kind: 'vault-deploy', chainId: args.registry.chainId })
+  if (!receipt.contractAddress) {
+    throw new Error('Operator delegation vault deploy receipt is missing contractAddress; the transaction was not a contract creation')
+  }
+  const vaultAddress = getAddress(receipt.contractAddress)
+  await assertVaultBytecode(client, vaultAddress, result.txHash)
+  return { txHash: result.txHash, vaultAddress }
+}
+
+export async function runVaultDepositTransaction(args: {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  vaultAddress: Address
+  callbacks: EffectCallbacks
+  flowId?: string
+}): Promise<{ txHash: string }> {
+  return withTxGuard('vault-deposit', () => runVaultDepositTransactionInner(args))
+}
+
+async function runVaultDepositTransactionInner(args: {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  vaultAddress: Address
+  callbacks: EffectCallbacks
+  flowId?: string
+}): Promise<{ txHash: string }> {
+  const { identity, registry, vaultAddress } = args
+  if (!identity.agentId) {
+    throw new Error('Cannot deposit token to operator delegation vault: agent token ID is missing')
+  }
+  const tokenOwner = getAddress(identity.ownerAddress ?? identity.address)
+  await assertVaultCanAcceptAgent({
+    registry,
+    vaultAddress,
+    agentId: BigInt(identity.agentId),
+  })
+  const encoded = encodeDepositAgent({
+    registry: getAddress(registry.identityRegistryAddress),
+    agentId: BigInt(identity.agentId),
+    walletAddress: tokenOwner,
+    vaultAddress,
+  })
+  const gasFeeClient = createErc8004PublicClient(registry)
+  const gasFee = await prepareTransactionGasFee({
+    client: gasFeeClient,
+    account: tokenOwner,
+    to: encoded.to,
+    data: encoded.data,
+  })
+  const result = await sendBrowserWalletTransaction({
+    chainId: registry.chainId,
+    expectedAccount: tokenOwner,
+    to: encoded.to,
+    data: encoded.data,
+    gas: gasFee.gas,
+    maxFeePerGas: gasFee.maxFeePerGas,
+    maxPriorityFeePerGas: gasFee.maxPriorityFeePerGas,
+    purpose: 'deposit-agent-vault',
+    onReady: args.callbacks.onWalletReady,
+    ...(args.flowId ? { flowId: args.flowId } : {}),
+  })
+  args.callbacks.onWalletReady(null)
+  const depositClient = createErc8004PublicClient(registry)
+  await awaitConfirmedReceipt(
+    depositClient,
+    result.txHash as Hex,
+    'Operator delegation vault deposit',
+    { kind: 'vault-deposit', chainId: registry.chainId },
+  )
+  return { txHash: result.txHash }
+}
+
+async function assertVaultCanAcceptAgent(args: {
+  registry: Erc8004RegistryConfig
+  vaultAddress: Address
+  agentId: bigint
+}): Promise<void> {
+  const client = createErc8004PublicClient(args.registry)
+  let held: readonly [Address, bigint, Address]
+  try {
+    held = await client.readContract({
+      address: getAddress(args.vaultAddress),
+      abi: OPERATOR_VAULT_ABI,
+      functionName: 'heldAgent',
+    }) as readonly [Address, bigint, Address]
+  } catch {
+    return
+  }
+  const [heldRegistry, heldAgentId, heldOwner] = held
+  if (!heldOwner || heldOwner.toLowerCase() === '0x0000000000000000000000000000000000000000') return
+  const expectedRegistry = getAddress(args.registry.identityRegistryAddress)
+  const sameAgent = heldRegistry.toLowerCase() === expectedRegistry.toLowerCase() && heldAgentId === args.agentId
+  if (sameAgent) {
+    throw new Error(`Agent vault ${getAddress(args.vaultAddress)} already holds ERC-8004 token #${args.agentId.toString()}. Publish the pending update instead of depositing again.`)
+  }
+  throw new Error(`Agent vault ${getAddress(args.vaultAddress)} already holds ERC-8004 token #${heldAgentId.toString()} for registry ${getAddress(heldRegistry)}. Deploy a fresh vault for this agent.`)
+}
+
+export async function runVaultUnwrapTransaction(args: {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  vaultAddress: Address
+  callbacks: EffectCallbacks
+  flowId?: string
+  agentId?: bigint
+}): Promise<{ txHash: string } | null> {
+  return withTxGuard('vault-unwrap', () => runVaultUnwrapTransactionInner(args))
+}
+
+async function runVaultUnwrapTransactionInner(args: {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  vaultAddress: Address
+  callbacks: EffectCallbacks
+  flowId?: string
+  agentId?: bigint
+}): Promise<{ txHash: string } | null> {
+  const { identity, registry, vaultAddress } = args
+  const targetAgentId = args.agentId ?? (identity.agentId ? BigInt(identity.agentId) : undefined)
+  if (targetAgentId === undefined) {
+    throw new Error('Cannot unwrap token from operator delegation vault: agent token ID is missing')
+  }
+  const baseState = (identity.state ?? {}) as Record<string, unknown>
+  const ownerAddressRaw = readOwnerAddressField(baseState)
+  const ownerAddress = ownerAddressRaw
+    ? getAddress(ownerAddressRaw)
+    : getAddress(identity.ownerAddress ?? identity.address)
+  const publicClient = createErc8004PublicClient(registry)
+  const status = await isAgentInVault({
+    client: publicClient,
+    vaultAddress,
+    registry: getAddress(registry.identityRegistryAddress),
+    agentId: targetAgentId,
+  })
+  if (!status.inVault) return null
+  const encoded = encodeUnwrapAgent({
+    registry: getAddress(registry.identityRegistryAddress),
+    agentId: targetAgentId,
+    recipient: ownerAddress,
+    vaultAddress,
+  })
+  const result = await sendBrowserWalletTransaction({
+    chainId: registry.chainId,
+    expectedAccount: ownerAddress,
+    to: encoded.to,
+    data: encoded.data,
+    purpose: 'unwrap-agent-vault',
+    onReady: args.callbacks.onWalletReady,
+    ...(args.flowId ? { flowId: args.flowId } : {}),
+  })
+  args.callbacks.onWalletReady(null)
+  await awaitConfirmedReceipt(
+    publicClient,
+    result.txHash as Hex,
+    'Operator delegation vault unwrap',
+    { kind: 'vault-unwrap', chainId: registry.chainId },
+  )
+  await confirmAgentWithdrawnFromVault({
+    client: publicClient,
+    vaultAddress,
+    registry: getAddress(registry.identityRegistryAddress),
+    agentId: targetAgentId,
+    recipient: ownerAddress,
+  })
+  return { txHash: result.txHash }
+}
+
+export async function runVaultWithdrawTransaction(args: {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  vaultAddress: Address
+  callbacks: EffectCallbacks
+  agentId?: bigint
+}): Promise<{ txHash: string; recipient: Address }> {
+  return withTxGuard('vault-withdraw', () => runVaultWithdrawTransactionInner(args))
+}
+
+async function runVaultWithdrawTransactionInner(args: {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  vaultAddress: Address
+  callbacks: EffectCallbacks
+  agentId?: bigint
+}): Promise<{ txHash: string; recipient: Address }> {
+  const { identity, registry, vaultAddress } = args
+  const targetAgentId = args.agentId ?? (identity.agentId ? BigInt(identity.agentId) : undefined)
+  if (targetAgentId === undefined) {
+    throw new Error('Cannot withdraw token: agent token ID is missing')
+  }
+  const publicClient = createErc8004PublicClient(registry)
+  const status = await isAgentInVault({
+    client: publicClient,
+    vaultAddress,
+    registry: getAddress(registry.identityRegistryAddress),
+    agentId: targetAgentId,
+  })
+  if (!status.inVault) {
+    throw new Error('Token is not currently held by the vault, nothing to unwrap')
+  }
+  if (!status.ownerAddress) {
+    throw new Error('Vault has no recorded depositor for this token; cannot determine recipient')
+  }
+  const recipient = getAddress(status.ownerAddress)
+  const encoded = encodeUnwrapAgent({
+    registry: getAddress(registry.identityRegistryAddress),
+    agentId: targetAgentId,
+    recipient,
+    vaultAddress,
+  })
+  const result = await sendBrowserWalletTransaction({
+    chainId: registry.chainId,
+    expectedAccount: recipient,
+    to: encoded.to,
+    data: encoded.data,
+    purpose: 'withdraw-vault',
+    onReady: args.callbacks.onWalletReady,
+  })
+  args.callbacks.onWalletReady(null)
+  await awaitConfirmedReceipt(
+    publicClient,
+    result.txHash as Hex,
+    'Operator delegation vault withdraw',
+    { kind: 'vault-withdraw', chainId: registry.chainId },
+  )
+  await confirmAgentWithdrawnFromVault({
+    client: publicClient,
+    vaultAddress,
+    registry: getAddress(registry.identityRegistryAddress),
+    agentId: targetAgentId,
+    recipient,
+  })
+  return { txHash: result.txHash, recipient }
+}