ethagent 1.1.2 → 2.0.0

package/src/identity/registry/fieldParsers.ts

@@ -0,0 +1,28 @@
+
+export function objectField(input: Record<string, unknown> | null | undefined, key: string): Record<string, unknown> | null {
+  if (!input) return null
+  const value = input[key]
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
+export function arrayField(input: Record<string, unknown> | null | undefined, key: string): Array<unknown> | null {
+  if (!input) return null
+  const value = input[key]
+  return Array.isArray(value) ? value : null
+}
+
+export function stringField(input: Record<string, unknown> | null | undefined, key: string): string | undefined {
+  const value = input?.[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+export function numberField(input: Record<string, unknown> | null | undefined, key: string): number | undefined {
+  const value = input?.[key]
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : undefined
+}
+
+export function booleanField(input: Record<string, unknown> | null | undefined, key: string): boolean | undefined {
+  const value = input?.[key]
+  return typeof value === 'boolean' ? value : undefined
+}

package/src/identity/registry/operatorVault/bytecode.ts

@@ -0,0 +1,98 @@
+import { getAddress, keccak256, type Address, type Hex, type PublicClient } from 'viem'
+import { OPERATOR_VAULT_RUNTIME_BYTECODE, OPERATOR_VAULT_RUNTIME_BYTECODE_HASH } from './constants.js'
+
+export class OperatorVaultBytecodeMismatchError extends Error {
+  readonly vaultAddress: Address
+  readonly observedHash: Hex | null
+  readonly observedLength: number
+  readonly expectedHash: Hex
+  readonly expectedLength: number
+  readonly txHash?: Hex
+  constructor(
+    vaultAddress: Address,
+    observedHash: Hex | null,
+    observedLength: number,
+    txHash?: Hex,
+  ) {
+    super(
+      'Deployed contract bytecode does not match the expected operator delegation vault. The deploy transaction may have been intercepted.',
+    )
+    this.name = 'OperatorVaultBytecodeMismatchError'
+    this.vaultAddress = vaultAddress
+    this.observedHash = observedHash
+    this.observedLength = observedLength
+    this.expectedHash = OPERATOR_VAULT_RUNTIME_BYTECODE_HASH
+    this.expectedLength = (OPERATOR_VAULT_RUNTIME_BYTECODE.length - 2) / 2
+    if (txHash) this.txHash = txHash
+  }
+}
+
+export type AssertVaultBytecodeClient = Pick<PublicClient, 'getBytecode'>
+
+export const OPERATOR_VAULT_POLL_MAX_ATTEMPTS = 5
+export const OPERATOR_VAULT_POLL_DELAY_MS = 1500
+export function delayMs(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function readVaultBytecodeWithPoll(
+  client: AssertVaultBytecodeClient,
+  address: Address,
+): Promise<Hex | undefined> {
+  let lastErr: unknown
+  let lastCode: Hex | undefined
+  for (let attempt = 0; attempt < OPERATOR_VAULT_POLL_MAX_ATTEMPTS; attempt++) {
+    if (attempt > 0) await delayMs(OPERATOR_VAULT_POLL_DELAY_MS)
+    try {
+      const code = await client.getBytecode({ address })
+      lastErr = undefined
+      lastCode = code
+      const isEmpty = !code || code === '0x'
+      if (!isEmpty) return code
+    } catch (err) {
+      lastErr = err
+      lastCode = undefined
+    }
+  }
+  if (lastErr) throw lastErr
+  return lastCode
+}
+
+export async function assertVaultBytecode(
+  client: AssertVaultBytecodeClient,
+  vaultAddress: Address,
+  txHash?: Hex,
+): Promise<void> {
+  const address = getAddress(vaultAddress)
+  const code = await readVaultBytecodeWithPoll(client, address)
+  if (!code || code === '0x') {
+    throw new OperatorVaultBytecodeMismatchError(address, null, 0, txHash)
+  }
+  const observedLength = (code.length - 2) / 2
+  const observed = keccak256(code).toLowerCase() as Hex
+  const expected = OPERATOR_VAULT_RUNTIME_BYTECODE_HASH.toLowerCase() as Hex
+  if (observed !== expected) {
+    throw new OperatorVaultBytecodeMismatchError(address, observed, observedLength, txHash)
+  }
+}
+
+function shortHash(hash: Hex): string {
+  return `${hash.slice(0, 18)}...${hash.slice(-6)}`
+}
+
+export function formatOperatorVaultBytecodeMismatchDetail(
+  err: OperatorVaultBytecodeMismatchError,
+): string {
+  const lines = [
+    `Vault address:   ${err.vaultAddress}`,
+  ]
+  if (err.txHash) lines.push(`Deploy tx:       ${err.txHash}`)
+  lines.push(`Expected hash:   ${shortHash(err.expectedHash)}`)
+  if (err.observedHash) {
+    lines.push(`Observed hash:   ${shortHash(err.observedHash)}`)
+    lines.push(`Observed length: ${err.observedLength} bytes (expected ${err.expectedLength})`)
+  } else {
+    lines.push(`Observed code:   none. Address has no code.`)
+  }
+  return lines.join('\n')
+}

package/src/identity/registry/operatorVault/constants.ts

@@ -0,0 +1,38 @@
+import { getAddress, keccak256, parseAbi, type Address, type Hex } from 'viem'
+
+export const OPERATOR_VAULT_ABI = parseAbi([
+  'constructor(address registry, uint256 agentId)',
+  'function agentOwner(address registry, uint256 agentId) view returns (address)',
+  'function metadataOperators(address registry, uint256 agentId, address operator) view returns (bool)',
+  'function heldAgent() view returns (address registry, uint256 agentId, address owner)',
+  'function setMetadataOperator(address registry, uint256 agentId, address operator, bool approved)',
+  'function unwrap(address registry, uint256 agentId, address recipient)',
+  'function rotateAgentURI(address registry, uint256 agentId, string newURI)',
+  'event AgentDeposited(address indexed registry, uint256 indexed agentId, address indexed owner)',
+  'event AgentUnwrapped(address indexed registry, uint256 indexed agentId, address indexed recipient)',
+  'event MetadataOperatorChanged(address indexed registry, uint256 indexed agentId, address indexed operator, bool approved)',
+  'event AgentURIRotated(address indexed registry, uint256 indexed agentId, string newURI, address indexed signer)',
+])
+
+export const OPERATOR_VAULT_ADDRESSES: Record<number, Address> = {
+}
+
+export function operatorVaultAddressForChain(chainId: number): Address | undefined {
+  const address = OPERATOR_VAULT_ADDRESSES[chainId]
+  return address ? getAddress(address) : undefined
+}
+
+export function resolveConfiguredOperatorVaultAddress(
+  operatorVaults: Readonly<Record<string, string>> | undefined,
+  chainId: number,
+): Address | undefined {
+  const fromConfig = operatorVaults?.[String(chainId)]
+  if (fromConfig) return getAddress(fromConfig)
+  return operatorVaultAddressForChain(chainId)
+}
+
+export const OPERATOR_VAULT_DEPLOY_BYTECODE: Hex = '0x608060405234801561001057600080fd5b5060405161090538038061090583398101604081905261002f91610058565b600080546001600160a01b0319166001600160a01b039390931692909217909155600155610092565b6000806040838503121561006b57600080fd5b82516001600160a01b038116811461008257600080fd5b6020939093015192949293505050565b610864806100a16000396000f3fe608060405234801561001057600080fd5b506004361061007d5760003560e01c80631c3bb2851161005b5780631c3bb2851461011157806324a3e2a1146101265780639a61ce8114610149578063b68f43451461015c57600080fd5b8063029ae47e146100825780631400a7e2146100b2578063150b7a02146100e5575b600080fd5b610095610090366004610602565b61016f565b6040516001600160a01b0390911681526020015b60405180910390f35b600254600354600454604080516001600160a01b03948516815260208101939093529216918101919091526060016100a9565b6100f86100f3366004610675565b61019a565b6040516001600160e01b031990911681526020016100a9565b61012461011f3660046106e4565b610293565b005b61013961013436600461073e565b610397565b60405190151581526020016100a9565b61012461015736600461077a565b6103d0565b61012461016a36600461073e565b6104a2565b600061017b83836105ab565b610186576000610193565b6004546001600160a01b03165b9392505050565b600080546001600160a01b0316331415806101b757506001548414155b156101d557604051639667ffdf60e01b815260040160405180910390fd5b6004546001600160a01b0316156101ff5760405163d5a8211560e01b815260040160405180910390fd5b60028054336001600160a01b0319918216179091556003859055600480549091166001600160a01b0387161790556005805460018101909155600003600019016102495760016005555b6040516001600160a01b03861690859033907f7b19af5fe09a0be4ed70b569401ce6fa0de072757b228cc2088350eccc2f987390600090a450630a85bd0160e11b95945050505050565b600061029f858561016f565b9050336001600160a01b038216148015906102c257506102c0858533610397565b155b156102e05760405163ea8e4eb560e01b815260040160405180910390fd5b604051630af28bd360e01b81526001600160a01b03861690630af28bd390610310908790879087906004016107f7565b600060405180830381600087803b15801561032a57600080fd5b505af115801561033e573d6000803e3d6000fd5b50505050336001600160a01b031684866001600160a01b03167fa455a129bb4260e5274d34dd213bcd11399667f80a0615e6cb375728d2e75a90868660405161038892919061081a565b60405180910390a45050505050565b60006103a384846105ab565b80156103c857506005546001600160a01b038316600090815260066020526040902054145b949350505050565b6103da848461016f565b6001600160a01b0316336001600160a01b03161461040b576040516330cd747160e01b815260040160405180910390fd5b8015610432576005546001600160a01b03831660009081526006602052604090205561044c565b6001600160a01b0382166000908152600660205260408120555b816001600160a01b031683856001600160a01b03167fea7d7802a5cc5520abde4345007961a980fcb27dca3030ca6aede6bdc58bd79e84604051610494911515815260200190565b60405180910390a450505050565b60006104ae848461016f565b9050336001600160a01b038216146104d9576040516330cd747160e01b815260040160405180910390fd5b600280546001600160a01b03199081169091556000600355600480549091168155604051632142170760e11b815230918101919091526001600160a01b038381166024830152604482018590528516906342842e0e90606401600060405180830381600087803b15801561054c57600080fd5b505af1158015610560573d6000803e3d6000fd5b50505050816001600160a01b031683856001600160a01b03167fa433e9204e6763dff9274d8c1febdbc7c60aa7d7e85c106d5b978372658438b860405160405180910390a450505050565b6004546000906001600160a01b0316158015906105d557506002546001600160a01b038481169116145b801561019357505060035414919050565b80356001600160a01b03811681146105fd57600080fd5b919050565b6000806040838503121561061557600080fd5b61061e836105e6565b946020939093013593505050565b60008083601f84011261063e57600080fd5b50813567ffffffffffffffff81111561065657600080fd5b60208301915083602082850101111561066e57600080fd5b9250929050565b60008060008060006080868803121561068d57600080fd5b610696866105e6565b94506106a4602087016105e6565b935060408601359250606086013567ffffffffffffffff8111156106c757600080fd5b6106d38882890161062c565b969995985093965092949392505050565b600080600080606085870312156106fa57600080fd5b610703856105e6565b935060208501359250604085013567ffffffffffffffff81111561072657600080fd5b6107328782880161062c565b95989497509550505050565b60008060006060848603121561075357600080fd5b61075c846105e6565b925060208401359150610771604085016105e6565b90509250925092565b6000806000806080858703121561079057600080fd5b610799856105e6565b9350602085013592506107ae604086016105e6565b9150606085013580151581146107c357600080fd5b939692955090935050565b81835281816020850137506000828201602090810191909152601f909101601f19169091010190565b8381526040602082015260006108116040830184866107ce565b95945050505050565b6020815260006103c86020830184866107ce56fea2646970667358221220dd5405c74ca871baa3fc981f170a85015cbe31e79a0e1034acc7154f51ae011664736f6c63430008180033'
+
+export const OPERATOR_VAULT_RUNTIME_BYTECODE: Hex = '0x608060405234801561001057600080fd5b506004361061007d5760003560e01c80631c3bb2851161005b5780631c3bb2851461011157806324a3e2a1146101265780639a61ce8114610149578063b68f43451461015c57600080fd5b8063029ae47e146100825780631400a7e2146100b2578063150b7a02146100e5575b600080fd5b610095610090366004610602565b61016f565b6040516001600160a01b0390911681526020015b60405180910390f35b600254600354600454604080516001600160a01b03948516815260208101939093529216918101919091526060016100a9565b6100f86100f3366004610675565b61019a565b6040516001600160e01b031990911681526020016100a9565b61012461011f3660046106e4565b610293565b005b61013961013436600461073e565b610397565b60405190151581526020016100a9565b61012461015736600461077a565b6103d0565b61012461016a36600461073e565b6104a2565b600061017b83836105ab565b610186576000610193565b6004546001600160a01b03165b9392505050565b600080546001600160a01b0316331415806101b757506001548414155b156101d557604051639667ffdf60e01b815260040160405180910390fd5b6004546001600160a01b0316156101ff5760405163d5a8211560e01b815260040160405180910390fd5b60028054336001600160a01b0319918216179091556003859055600480549091166001600160a01b0387161790556005805460018101909155600003600019016102495760016005555b6040516001600160a01b03861690859033907f7b19af5fe09a0be4ed70b569401ce6fa0de072757b228cc2088350eccc2f987390600090a450630a85bd0160e11b95945050505050565b600061029f858561016f565b9050336001600160a01b038216148015906102c257506102c0858533610397565b155b156102e05760405163ea8e4eb560e01b815260040160405180910390fd5b604051630af28bd360e01b81526001600160a01b03861690630af28bd390610310908790879087906004016107f7565b600060405180830381600087803b15801561032a57600080fd5b505af115801561033e573d6000803e3d6000fd5b50505050336001600160a01b031684866001600160a01b03167fa455a129bb4260e5274d34dd213bcd11399667f80a0615e6cb375728d2e75a90868660405161038892919061081a565b60405180910390a45050505050565b60006103a384846105ab565b80156103c857506005546001600160a01b038316600090815260066020526040902054145b949350505050565b6103da848461016f565b6001600160a01b0316336001600160a01b03161461040b576040516330cd747160e01b815260040160405180910390fd5b8015610432576005546001600160a01b03831660009081526006602052604090205561044c565b6001600160a01b0382166000908152600660205260408120555b816001600160a01b031683856001600160a01b03167fea7d7802a5cc5520abde4345007961a980fcb27dca3030ca6aede6bdc58bd79e84604051610494911515815260200190565b60405180910390a450505050565b60006104ae848461016f565b9050336001600160a01b038216146104d9576040516330cd747160e01b815260040160405180910390fd5b600280546001600160a01b03199081169091556000600355600480549091168155604051632142170760e11b815230918101919091526001600160a01b038381166024830152604482018590528516906342842e0e90606401600060405180830381600087803b15801561054c57600080fd5b505af1158015610560573d6000803e3d6000fd5b50505050816001600160a01b031683856001600160a01b03167fa433e9204e6763dff9274d8c1febdbc7c60aa7d7e85c106d5b978372658438b860405160405180910390a450505050565b6004546000906001600160a01b0316158015906105d557506002546001600160a01b038481169116145b801561019357505060035414919050565b80356001600160a01b03811681146105fd57600080fd5b919050565b6000806040838503121561061557600080fd5b61061e836105e6565b946020939093013593505050565b60008083601f84011261063e57600080fd5b50813567ffffffffffffffff81111561065657600080fd5b60208301915083602082850101111561066e57600080fd5b9250929050565b60008060008060006080868803121561068d57600080fd5b610696866105e6565b94506106a4602087016105e6565b935060408601359250606086013567ffffffffffffffff8111156106c757600080fd5b6106d38882890161062c565b969995985093965092949392505050565b600080600080606085870312156106fa57600080fd5b610703856105e6565b935060208501359250604085013567ffffffffffffffff81111561072657600080fd5b6107328782880161062c565b95989497509550505050565b60008060006060848603121561075357600080fd5b61075c846105e6565b925060208401359150610771604085016105e6565b90509250925092565b6000806000806080858703121561079057600080fd5b610799856105e6565b9350602085013592506107ae604086016105e6565b9150606085013580151581146107c357600080fd5b939692955090935050565b81835281816020850137506000828201602090810191909152601f909101601f19169091010190565b8381526040602082015260006108116040830184866107ce565b95945050505050565b6020815260006103c86020830184866107ce56fea2646970667358221220dd5405c74ca871baa3fc981f170a85015cbe31e79a0e1034acc7154f51ae011664736f6c63430008180033'
+
+export const OPERATOR_VAULT_RUNTIME_BYTECODE_HASH: Hex = keccak256(OPERATOR_VAULT_RUNTIME_BYTECODE)

package/src/identity/registry/operatorVault/read.ts

@@ -0,0 +1,246 @@
+import { getAddress, parseAbi, parseAbiItem, type Address, type PublicClient } from 'viem'
+import { OPERATOR_VAULT_ABI } from './constants.js'
+import { delayMs, OPERATOR_VAULT_POLL_DELAY_MS, OPERATOR_VAULT_POLL_MAX_ATTEMPTS } from './bytecode.js'
+
+const DISCOVER_LOG_WINDOW_MAX_ATTEMPTS = 3
+const DISCOVER_LOG_WINDOW_DELAY_MS = 2000
+
+export type OperatorVaultReadClient = Pick<PublicClient, 'readContract'>
+
+const ERC721_OWNER_OF_ABI = parseAbi([
+  'function ownerOf(uint256 tokenId) view returns (address)',
+])
+
+export type DiscoverPriorVaultClient = Pick<PublicClient, 'readContract' | 'getBytecode'>
+
+export type DiscoverPriorVaultArgs = {
+  client: DiscoverPriorVaultClient
+  registry: Address
+  agentId: bigint
+  expectedOwner: Address
+}
+
+export async function discoverPriorVaultFromTokenOwner(
+  args: DiscoverPriorVaultArgs,
+): Promise<{ found: false } | { found: true; vaultAddress: Address }> {
+  const registryAddr = getAddress(args.registry)
+  const expected = getAddress(args.expectedOwner).toLowerCase()
+  const tokenOwner = await args.client.readContract({
+    address: registryAddr,
+    abi: ERC721_OWNER_OF_ABI,
+    functionName: 'ownerOf',
+    args: [args.agentId],
+  }) as Address
+  if (!tokenOwner || tokenOwner.toLowerCase() === '0x0000000000000000000000000000000000000000') {
+    return { found: false }
+  }
+  if (tokenOwner.toLowerCase() === expected) {
+    return { found: false }
+  }
+  const candidate = getAddress(tokenOwner)
+  const code = await args.client.getBytecode({ address: candidate })
+  if (!code || code === '0x') return { found: false }
+  let vaultLevelOwner: Address
+  try {
+    vaultLevelOwner = await args.client.readContract({
+      address: candidate,
+      abi: OPERATOR_VAULT_ABI,
+      functionName: 'agentOwner',
+      args: [registryAddr, args.agentId],
+    }) as Address
+  } catch {
+    return { found: false }
+  }
+  if (!vaultLevelOwner || vaultLevelOwner.toLowerCase() !== expected) {
+    return { found: false }
+  }
+  return { found: true, vaultAddress: candidate }
+}
+
+export type IsAgentInVaultArgs = {
+  client: OperatorVaultReadClient
+  vaultAddress: Address
+  registry: Address
+  agentId: bigint
+}
+
+export async function isAgentInVault(
+  args: IsAgentInVaultArgs,
+): Promise<{ inVault: boolean; ownerAddress?: Address }> {
+  const owner = await args.client.readContract({
+    address: getAddress(args.vaultAddress),
+    abi: OPERATOR_VAULT_ABI,
+    functionName: 'agentOwner',
+    args: [getAddress(args.registry), args.agentId],
+  }) as Address
+  if (!owner || owner.toLowerCase() === '0x0000000000000000000000000000000000000000') {
+    return { inVault: false }
+  }
+  return { inVault: true, ownerAddress: getAddress(owner) }
+}
+
+export async function confirmAgentInVault(
+  args: IsAgentInVaultArgs,
+): Promise<{ inVault: true; ownerAddress: Address }> {
+  let lastErr: unknown
+  for (let attempt = 0; attempt < OPERATOR_VAULT_POLL_MAX_ATTEMPTS; attempt++) {
+    if (attempt > 0) await delayMs(OPERATOR_VAULT_POLL_DELAY_MS)
+    try {
+      const status = await isAgentInVault(args)
+      lastErr = undefined
+      if (status.inVault && status.ownerAddress) {
+        return { inVault: true, ownerAddress: status.ownerAddress }
+      }
+    } catch (err) {
+      lastErr = err
+    }
+  }
+  if (lastErr) throw lastErr
+  throw new Error(
+    `Operator delegation vault ${getAddress(args.vaultAddress)} does not hold agent token #${args.agentId.toString()} for registry ${getAddress(args.registry)} after the deposit-confirmation budget was exhausted. The deposit transaction may have been re-orged or applied to the wrong vault. Re-run the switch.`,
+  )
+}
+
+export type ConfirmAgentWithdrawnArgs = IsAgentInVaultArgs & {
+  recipient: Address
+}
+
+export async function confirmAgentWithdrawnFromVault(
+  args: ConfirmAgentWithdrawnArgs,
+): Promise<{ inVault: false; ownerAddress: Address }> {
+  const recipient = getAddress(args.recipient)
+  let lastErr: unknown
+  let lastObserved: string | undefined
+  for (let attempt = 0; attempt < OPERATOR_VAULT_POLL_MAX_ATTEMPTS; attempt++) {
+    if (attempt > 0) await delayMs(OPERATOR_VAULT_POLL_DELAY_MS)
+    try {
+      const status = await isAgentInVault(args)
+      const tokenOwner = await args.client.readContract({
+        address: getAddress(args.registry),
+        abi: ERC721_OWNER_OF_ABI,
+        functionName: 'ownerOf',
+        args: [args.agentId],
+      }) as Address
+      const ownerAddress = getAddress(tokenOwner)
+      lastErr = undefined
+      lastObserved = status.inVault
+        ? `vault owner ${status.ownerAddress ?? 'unknown'}, token owner ${ownerAddress}`
+        : `token owner ${ownerAddress}`
+      if (!status.inVault && ownerAddress.toLowerCase() === recipient.toLowerCase()) {
+        return { inVault: false, ownerAddress }
+      }
+    } catch (err) {
+      lastErr = err
+    }
+  }
+  if (lastErr) throw lastErr
+  throw new Error(
+    `Operator delegation vault ${getAddress(args.vaultAddress)} did not release agent token #${args.agentId.toString()} to ${recipient} after the withdraw-confirmation budget was exhausted. Last observed: ${lastObserved ?? 'unknown'}.`,
+  )
+}
+
+const AGENT_DEPOSITED_EVENT = parseAbiItem(
+  'event AgentDeposited(address indexed registry, uint256 indexed agentId, address indexed owner)',
+)
+
+export type DiscoverVaultedTokensArgs = {
+  client: PublicClient
+  vaultAddress: Address
+  registry: Address
+  depositorAddress: Address
+  fromBlock?: bigint
+}
+
+const DISCOVER_VAULTED_TOKENS_BLOCK_WINDOW = 9_000n
+
+export async function discoverVaultedTokens(
+  args: DiscoverVaultedTokensArgs,
+): Promise<Array<{ registry: Address; agentId: bigint }>> {
+  const vaultAddr = getAddress(args.vaultAddress)
+  const registryAddr = getAddress(args.registry)
+  const depositor = getAddress(args.depositorAddress)
+  const fromBlock = args.fromBlock ?? 0n
+  const latest = await args.client.getBlockNumber()
+  const fetchWindow = async (cursorFrom: bigint, cursorTo: bigint) =>
+    args.client.getLogs({
+      address: vaultAddr,
+      event: AGENT_DEPOSITED_EVENT,
+      args: { registry: registryAddr, owner: depositor },
+      fromBlock: cursorFrom,
+      toBlock: cursorTo,
+    })
+  type DepositLog = Awaited<ReturnType<typeof fetchWindow>>[number]
+  const fetchWindowWithRetry = async (cursorFrom: bigint, cursorTo: bigint): Promise<DepositLog[]> => {
+    let lastErr: unknown
+    for (let attempt = 0; attempt < DISCOVER_LOG_WINDOW_MAX_ATTEMPTS; attempt++) {
+      if (attempt > 0) await delayMs(DISCOVER_LOG_WINDOW_DELAY_MS)
+      try {
+        return await fetchWindow(cursorFrom, cursorTo)
+      } catch (err) {
+        lastErr = err
+      }
+    }
+    throw lastErr ?? new Error(`failed to fetch AgentDeposited logs for window [${cursorFrom},${cursorTo}]`)
+  }
+  const logs: DepositLog[] = []
+  let cursor = fromBlock
+  while (cursor <= latest) {
+    const windowEnd = cursor + DISCOVER_VAULTED_TOKENS_BLOCK_WINDOW - 1n
+    const toBlock = windowEnd < latest ? windowEnd : latest
+    const window = await fetchWindowWithRetry(cursor, toBlock)
+    logs.push(...window)
+    if (toBlock === latest) break
+    cursor = toBlock + 1n
+  }
+  const seen = new Set<string>()
+  const candidates: Array<{ registry: Address; agentId: bigint }> = []
+  for (const log of logs) {
+    const agentId = log.args.agentId
+    if (agentId === undefined) continue
+    const key = `${registryAddr.toLowerCase()}:${agentId.toString()}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    candidates.push({ registry: registryAddr, agentId })
+  }
+  const out: Array<{ registry: Address; agentId: bigint }> = []
+  for (const candidate of candidates) {
+    const status = await isAgentInVault({
+      client: args.client,
+      vaultAddress: vaultAddr,
+      registry: candidate.registry,
+      agentId: candidate.agentId,
+    })
+    if (status.inVault && status.ownerAddress?.toLowerCase() === depositor.toLowerCase()) {
+      out.push(candidate)
+    }
+  }
+  return out
+}
+
+export type ReadMetadataOperatorsArgs = {
+  client: OperatorVaultReadClient
+  vaultAddress: Address
+  registry: Address
+  agentId: bigint
+  candidates: readonly Address[]
+}
+
+export async function readMetadataOperators(
+  args: ReadMetadataOperatorsArgs,
+): Promise<Record<Address, boolean>> {
+  const out: Record<Address, boolean> = {}
+  for (const candidate of args.candidates) {
+    try {
+      const approved = await args.client.readContract({
+        address: getAddress(args.vaultAddress),
+        abi: OPERATOR_VAULT_ABI,
+        functionName: 'metadataOperators',
+        args: [getAddress(args.registry), args.agentId, getAddress(candidate)],
+      }) as boolean
+      out[candidate] = Boolean(approved)
+    } catch {
+      out[candidate] = false
+    }
+  }
+  return out
+}

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

@@ -0,0 +1,81 @@
+import { encodeFunctionData, getAddress, parseAbi, type Address, type Hex } from 'viem'
+import { OPERATOR_VAULT_ABI } from './constants.js'
+
+const ERC721_SAFE_TRANSFER_ABI = parseAbi([
+  'function safeTransferFrom(address from, address to, uint256 tokenId)',
+])
+
+export type DepositAgentArgs = {
+  registry: Address
+  agentId: bigint
+  walletAddress: Address
+  vaultAddress: Address
+}
+
+export function encodeDepositAgent(args: DepositAgentArgs): { to: Address; data: Hex } {
+  return {
+    to: getAddress(args.registry),
+    data: encodeFunctionData({
+      abi: ERC721_SAFE_TRANSFER_ABI,
+      functionName: 'safeTransferFrom',
+      args: [getAddress(args.walletAddress), getAddress(args.vaultAddress), args.agentId],
+    }),
+  }
+}
+
+export type SetMetadataOperatorArgs = {
+  registry: Address
+  agentId: bigint
+  operator: Address
+  approved: boolean
+  vaultAddress: Address
+}
+
+export function encodeSetMetadataOperator(args: SetMetadataOperatorArgs): { to: Address; data: Hex } {
+  return {
+    to: getAddress(args.vaultAddress),
+    data: encodeFunctionData({
+      abi: OPERATOR_VAULT_ABI,
+      functionName: 'setMetadataOperator',
+      args: [getAddress(args.registry), args.agentId, getAddress(args.operator), args.approved],
+    }),
+  }
+}
+
+export type RotateAgentURIArgs = {
+  registry: Address
+  agentId: bigint
+  newURI: string
+  vaultAddress: Address
+}
+
+export function encodeRotateAgentURI(args: RotateAgentURIArgs): { to: Address; data: Hex } {
+  return {
+    to: getAddress(args.vaultAddress),
+    data: encodeFunctionData({
+      abi: OPERATOR_VAULT_ABI,
+      functionName: 'rotateAgentURI',
+      args: [getAddress(args.registry), args.agentId, args.newURI],
+    }),
+  }
+}
+
+export type UnwrapAgentArgs = {
+  registry: Address
+  agentId: bigint
+  recipient: Address
+  vaultAddress: Address
+}
+
+export function encodeUnwrapAgent(
+  args: UnwrapAgentArgs,
+): { to: Address; data: Hex } {
+  return {
+    to: getAddress(args.vaultAddress),
+    data: encodeFunctionData({
+      abi: OPERATOR_VAULT_ABI,
+      functionName: 'unwrap',
+      args: [getAddress(args.registry), args.agentId, getAddress(args.recipient)],
+    }),
+  }
+}

package/src/identity/registry/operatorVault.ts

@@ -0,0 +1,44 @@
+export {
+  OPERATOR_VAULT_ABI,
+  OPERATOR_VAULT_ADDRESSES,
+  OPERATOR_VAULT_DEPLOY_BYTECODE,
+  OPERATOR_VAULT_RUNTIME_BYTECODE,
+  OPERATOR_VAULT_RUNTIME_BYTECODE_HASH,
+  operatorVaultAddressForChain,
+  resolveConfiguredOperatorVaultAddress,
+} from './operatorVault/constants.js'
+export {
+  OperatorVaultBytecodeMismatchError,
+  assertVaultBytecode,
+  formatOperatorVaultBytecodeMismatchDetail,
+} from './operatorVault/bytecode.js'
+export type { AssertVaultBytecodeClient } from './operatorVault/bytecode.js'
+export {
+  encodeDepositAgent,
+  encodeRotateAgentURI,
+  encodeSetMetadataOperator,
+  encodeUnwrapAgent,
+} from './operatorVault/transactions.js'
+export type {
+  DepositAgentArgs,
+  RotateAgentURIArgs,
+  SetMetadataOperatorArgs,
+  UnwrapAgentArgs,
+} from './operatorVault/transactions.js'
+export {
+  confirmAgentWithdrawnFromVault,
+  confirmAgentInVault,
+  discoverPriorVaultFromTokenOwner,
+  discoverVaultedTokens,
+  isAgentInVault,
+  readMetadataOperators,
+} from './operatorVault/read.js'
+export type {
+  ConfirmAgentWithdrawnArgs,
+  DiscoverPriorVaultArgs,
+  DiscoverPriorVaultClient,
+  DiscoverVaultedTokensArgs,
+  IsAgentInVaultArgs,
+  OperatorVaultReadClient,
+  ReadMetadataOperatorsArgs,
+} from './operatorVault/read.js'

package/src/identity/storage/ipfs.ts

@@ -1,16 +1,10 @@
 export const PINATA_UPLOAD_API_URL = 'https://uploads.pinata.cloud/v3/files'
 export const PINATA_AUTH_TEST_URL = 'https://api.pinata.cloud/data/testAuthentication'
-export const DEFAULT_PINATA_GATEWAY_URL = 'https://gateway.pinata.cloud'
+const DEFAULT_PINATA_GATEWAY_URL = 'https://gateway.pinata.cloud'
 export const DEFAULT_IPFS_API_URL = process.env.ETHAGENT_IPFS_API_URL?.trim() || PINATA_UPLOAD_API_URL
 
 export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>
 
-export type IpfsClient = {
-  apiUrl: string
-  add: (content: string | Uint8Array) => Promise<IpfsAddResult>
-  cat: (cid: string) => Promise<Uint8Array>
-}
-
 export type IpfsAddResult = {
   cid: string
   pinVerified: boolean
@@ -21,19 +15,6 @@ type IpfsOptions = {
   pinataJwt?: string
 }
 
-export function createIpfsClient(apiUrl = DEFAULT_IPFS_API_URL, fetchImpl: FetchLike = fetch, options: IpfsOptions = {}): IpfsClient {
-  const base = normalizeApiUrl(apiUrl)
-  return {
-    apiUrl: base,
-    add: content => addToIpfs(base, content, fetchImpl, options),
-    cat: cid => catFromIpfs(base, cid, fetchImpl),
-  }
-}
-
-export function needsPinataJwt(apiUrl = DEFAULT_IPFS_API_URL, options: IpfsOptions = {}): boolean {
-  return isPinataUploadUrl(apiUrl) && !pinataJwt(options)
-}
-
 export function extractPinataJwt(input: string): string {
   const trimmed = input.trim()
   const matches = trimmed.match(/\b[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g) ?? []
@@ -111,11 +92,13 @@ export async function catFromIpfs(
   apiUrl: string,
   cid: string,
   fetchImpl: FetchLike = fetch,
+  options: { signal?: AbortSignal } = {},
 ): Promise<Uint8Array> {
-  if (isPinataUploadUrl(apiUrl)) return catFromPinata(cid, fetchImpl)
+  if (isPinataUploadUrl(apiUrl)) return catFromPinata(cid, fetchImpl, options.signal)
   const arg = encodeURIComponent(cid.trim())
   const response = await fetchImpl(`${normalizeApiUrl(apiUrl)}/api/v0/cat?arg=${arg}`, {
     method: 'POST',
+    ...(options.signal ? { signal: options.signal } : {}),
   })
   if (!response.ok) throw new Error(`IPFS cat failed: ${response.status} ${response.statusText}`)
   return new Uint8Array(await response.arrayBuffer())
@@ -163,17 +146,36 @@ async function addFileToPinata(
   const data = await response.json() as { data?: { cid?: string }; IpfsHash?: string; Hash?: string; Cid?: string }
   const cid = data.data?.cid ?? data.IpfsHash ?? data.Hash ?? data.Cid
   if (!cid) throw new Error('IPFS upload response did not include a CID')
-  return { cid, pinVerified: true, provider: 'pinata' }
+  const verified = await verifyCidReachable(cid, fetchImpl)
+  return { cid, pinVerified: verified, provider: 'pinata' }
+}
+
+async function verifyCidReachable(
+  cid: string,
+  fetchImpl: FetchLike,
+): Promise<boolean> {
+  const gateway = normalizeApiUrl(process.env.PINATA_GATEWAY_URL?.trim() || DEFAULT_PINATA_GATEWAY_URL)
+  const path = cid.trim().split('/').map(part => encodeURIComponent(part)).join('/')
+  const url = `${gateway}/ipfs/${path}`
+  for (const delayMs of [0, 1500]) {
+    if (delayMs > 0) await new Promise(resolve => setTimeout(resolve, delayMs))
+    try {
+      const response = await fetchImpl(url, { method: 'HEAD' })
+      if (response.ok) return true
+    } catch {
+    }
+  }
+  return false
 }
 
 function pinataJwt(options: IpfsOptions): string | undefined {
   return options.pinataJwt?.trim() || process.env.PINATA_JWT?.trim() || undefined
 }
 
-async function catFromPinata(cid: string, fetchImpl: FetchLike): Promise<Uint8Array> {
+async function catFromPinata(cid: string, fetchImpl: FetchLike, signal?: AbortSignal): Promise<Uint8Array> {
   const gateway = normalizeApiUrl(process.env.PINATA_GATEWAY_URL?.trim() || DEFAULT_PINATA_GATEWAY_URL)
   const path = cid.trim().split('/').map(part => encodeURIComponent(part)).join('/')
-  const response = await fetchImpl(`${gateway}/ipfs/${path}`)
+  const response = await fetchImpl(`${gateway}/ipfs/${path}`, signal ? { signal } : {})
   if (!response.ok) throw new Error(`IPFS fetch failed: ${response.status} ${response.statusText}`)
   return new Uint8Array(await response.arrayBuffer())
 }

package/src/identity/wallet/browserWallet/gas.ts

@@ -0,0 +1,41 @@
+import { numberToHex } from 'viem'
+import type {
+  PreparedGasFee,
+  PrepareTransactionGasFeeArgs,
+  PrepareTransactionGasFeeClient,
+} from './types.js'
+
+const GAS_FEE_PREP_MAX_ATTEMPTS = 5
+const GAS_FEE_PREP_DELAY_MS = 1500
+
+function gasFeeDelay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+export async function prepareTransactionGasFee(args: PrepareTransactionGasFeeArgs): Promise<PreparedGasFee> {
+  let lastErr: unknown
+  for (let attempt = 0; attempt < GAS_FEE_PREP_MAX_ATTEMPTS; attempt++) {
+    if (attempt > 0) await gasFeeDelay(GAS_FEE_PREP_DELAY_MS)
+    try {
+      const estimateArgs: Parameters<PrepareTransactionGasFeeClient['estimateGas']>[0] = {
+        account: args.account,
+        data: args.data,
+        ...(args.to ? { to: args.to } : {}),
+        ...(args.value !== undefined ? { value: args.value } : {}),
+      }
+      const [gas, fees] = await Promise.all([
+        args.client.estimateGas(estimateArgs),
+        args.client.estimateFeesPerGas(),
+      ])
+      const gasWithBuffer = (gas * 12n) / 10n
+      return {
+        gas: numberToHex(gasWithBuffer),
+        maxFeePerGas: numberToHex(fees.maxFeePerGas),
+        maxPriorityFeePerGas: numberToHex(fees.maxPriorityFeePerGas),
+      }
+    } catch (err) {
+      lastErr = err
+    }
+  }
+  throw lastErr ?? new Error('failed to prepare transaction gas/fee')
+}