ethagent 3.3.3 → 4.0.0

package/src/identity/{hub → manager}/shared/utils.ts

@@ -1,10 +1,7 @@
 import type { EthagentConfig, EthagentIdentity } from '../../../storage/config.js'
-import { supportedErc8004ChainForId } from '../../registry/erc8004.js'
 import { snapshotSaveRequiresOwnerSigner } from '../continuity/snapshot.js'
-import type { IdentityHubInitialAction } from '../types.js'
-import type { ProfileUpdates, Step } from '../identityHubReducer.js'
-
-const MIN_BUSY_ERROR_MS = 2000
+import type { IdentityManagerInitialAction } from '../types.js'
+import type { ProfileUpdates, Step } from '../reducer.js'
 
 export function isWalletCancelled(err: unknown): boolean {
   if (!err) return false
@@ -18,9 +15,7 @@ export function isStorageError(err: unknown): boolean {
   return /pinata|ipfs|pin|storage/i.test(message)
 }
 
-export function chainLabel(chainId: number): string {
-  return supportedErc8004ChainForId(chainId)?.name ?? `chain ${chainId}`
-}
+const MIN_BUSY_ERROR_MS = 2000
 
 export function waitForMinimumBusyTime(startedAt: number): Promise<void> {
   const remaining = MIN_BUSY_ERROR_MS - (Date.now() - startedAt)
@@ -51,11 +46,12 @@ export function rebackupWalletApprovalView(
   }
 }
 
-export function isCreateStep(step: Step): step is Extract<Step, { kind: 'replace-confirm' | 'create-name' | 'create-description' | 'create-custody' | 'create-preflight' | 'create-registry' | 'create-signing' | 'create-storage' }> {
+export function isCreateStep(step: Step): step is Extract<Step, { kind: 'replace-confirm' | 'create-name' | 'create-description' | 'create-custody' | 'create-import' | 'create-preflight' | 'create-registry' | 'create-signing' | 'create-storage' }> {
   return step.kind === 'replace-confirm'
     || step.kind === 'create-name'
     || step.kind === 'create-description'
     || step.kind === 'create-custody'
+    || step.kind === 'create-import'
     || step.kind === 'create-preflight'
     || step.kind === 'create-registry'
     || step.kind === 'create-signing'
@@ -67,7 +63,7 @@ export function isRestoreStep(step: Step): step is Exclude<Extract<Step, { kind:
 }
 
 export function initialStepForAction(
-  action: IdentityHubInitialAction | undefined,
+  action: IdentityManagerInitialAction | undefined,
   config: EthagentConfig | undefined,
 ): Step {
   if (action === 'create') return config?.identity ? { kind: 'replace-confirm', next: 'create' } : { kind: 'create-name' }

package/src/identity/{hub → manager}/transfer/TokenTransferFlow.tsx

@@ -9,7 +9,7 @@ import type {
   EffectCallbacks,
   TokenTransferProgress,
 } from '../shared/effects/types.js'
-import type { Step } from '../identityHubReducer.js'
+import type { Step } from '../reducer.js'
 import { BusyScreen } from '../shared/components/BusyScreen.js'
 import { RebackupStorageScreen } from '../continuity/RebackupStorageScreen.js'
 import {
@@ -87,7 +87,7 @@ export const TokenTransferFlow: React.FC<TokenTransferFlowProps> = ({
     return (
       <BusyScreen
         title="Resolve Receiver Wallet"
-        subtitle={`Resolving ${step.targetHandle} before preparing the transfer snapshot.`}
+        subtitle={`Resolving ${step.targetHandle}.`}
         label="checking ens or address..."
         onCancel={() => {
           resolveAbortRef.current?.abort()
@@ -158,5 +158,5 @@ function networkLabelForChainId(chainId: number): string {
 
 function tokenTransferBackHint(returnTo: Step | undefined): string {
   if (returnTo?.kind === 'edit-profile-ens') return 'Return to ENS setup'
-  return 'Return to Identity Hub menu'
+  return 'Return to menu'
 }

package/src/identity/{hub → manager}/transfer/TokenTransferScreens.tsx

@@ -16,7 +16,6 @@ import { FlowTimeline } from '../shared/components/FlowTimeline.js'
 import { OPEN_BROWSER_HINT } from '../shared/components/WalletApprovalScreen.js'
 
 const TRANSFER_STEPS = ['Choose Receiver', 'Sender Signs', 'Receiver Signs', 'Sender Updates URI', 'Transfer Token']
-const APPROVAL_GUARDRAIL = 'No approve(), setApprovalForAll(), transferFrom(), or token approval is requested.'
 
 type TokenTransferTargetScreenProps = {
   identity: EthagentIdentity
@@ -49,12 +48,10 @@ export const TokenTransferTargetScreen: React.FC<TokenTransferTargetScreenProps>
         <StatusRow label="Network" value={tokenNetworkLabel} />
         <StatusRow label="Sender" value={senderValue} />
         <Box marginTop={1} flexDirection="column">
-          <Text color={theme.textSubtle}>Use this before any ERC-8004 token transfer.</Text>
-          <Text color={theme.textSubtle}>Both signed wallets can read this snapshot; after transfer, restore with the receiver wallet.</Text>
-          <Text color={theme.textSubtle}>{APPROVAL_GUARDRAIL}</Text>
           {custodyMode === 'advanced' ? (
-            <Text color={theme.textSubtle}>Advanced custody: connect the owner wallet ({senderValue}) to sign as sender.</Text>
+            <Text color={theme.textSubtle}>Advanced custody: sign as the owner wallet.</Text>
           ) : null}
+          <Text color={theme.textSubtle}>No token approval is requested.</Text>
         </Box>
         <Box marginTop={1} flexDirection="column">
           <TextInput
@@ -180,7 +177,6 @@ export const TokenTransferReadyScreen: React.FC<TokenTransferReadyScreenProps> =
     footer={footer}
   >
     <Box flexDirection="column">
-      <Text color={theme.text}>Snapshot published. Transfer the ERC-8004 token externally on {tokenNetworkLabel} from sender to receiver.</Text>
       <Box marginTop={1} flexDirection="column">
         <StatusRow label="Token" value={identity.agentId ? `#${identity.agentId}` : 'not created'} tone={identity.agentId ? 'ok' : 'warn'} />
         <StatusRow label="Network" value={tokenNetworkLabel} tone="ok" />
@@ -190,10 +186,8 @@ export const TokenTransferReadyScreen: React.FC<TokenTransferReadyScreenProps> =
         <StatusRow label="Token URI tx" value={shortHash(txHash)} tone="ok" />
       </Box>
       <Box marginTop={1} flexDirection="column">
-        <Text color={theme.textSubtle}>Use this process for every ERC-8004 token transfer.</Text>
-        <Text color={theme.textSubtle}>Both sender and receiver signatures can decrypt this snapshot.</Text>
-        <Text color={theme.textSubtle}>After transfer, use Switch Agent with the receiver wallet.</Text>
-        <Text color={theme.textSubtle}>{APPROVAL_GUARDRAIL}</Text>
+        <Text color={theme.textSubtle}>Transfer the token externally, then restore with the receiver wallet.</Text>
+        <Text color={theme.textSubtle}>No token approval is requested.</Text>
       </Box>
       <Box marginTop={1}>
         <Select<'back'>

package/src/identity/{hub → manager}/transfer/effects.ts

@@ -27,7 +27,7 @@ import {
 import { resolveValidatedPinataJwt, savePinataJwt } from '../../storage/pinataJwt.js'
 import { openBrowserWalletSession } from '../../wallet/browserWallet.js'
 import { resolveEnsAddress } from '../../ens/ensLookup.js'
-import type { Step } from '../identityHubReducer.js'
+import type { Step } from '../reducer.js'
 import type { EffectCallbacks } from '../shared/effects/types.js'
 import { awaitConfirmedReceipt } from '../shared/effects/receipts.js'
 import {

package/src/identity/{hub → manager}/types.ts

@@ -1,17 +1,16 @@
 import type { EthagentConfig, EthagentIdentity } from '../../storage/config.js'
 
-export type IdentityHubResult =
+export type IdentityManagerResult =
   | { kind: 'token'; identity: EthagentIdentity }
   | { kind: 'updated'; config: EthagentConfig; message: string }
-  | { kind: 'skip' }
   | { kind: 'cancel' }
 
-export type IdentityHubInitialAction = 'create' | 'load' | 'settings' | 'save-snapshot' | 'save-prompt'
+export type IdentityManagerInitialAction = 'create' | 'load' | 'settings' | 'save-snapshot' | 'save-prompt'
 
-export type IdentityHubProps = {
+export type IdentityManagerProps = {
   mode: 'first-run' | 'manage'
   config?: EthagentConfig
-  initialAction?: IdentityHubInitialAction
-  onComplete: (result: IdentityHubResult) => void
+  initialAction?: IdentityManagerInitialAction
+  onComplete: (result: IdentityManagerResult) => void
   onConfigChange?: (config: EthagentConfig) => void
 }

package/src/identity/{hub/useIdentityHubContinuity.ts → manager/useContinuity.ts}

@@ -1,4 +1,5 @@
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useState } from 'react'
+import { watch, type FSWatcher } from 'node:fs'
 import type { EthagentIdentity } from '../../storage/config.js'
 import { catFromIpfs, DEFAULT_IPFS_API_URL } from '../storage/ipfs.js'
 import {
@@ -19,21 +20,37 @@ import {
 import type { SkillVisibility } from '../continuity/skills/types.js'
 import { syncAgentCardManifest } from '../continuity/skills/publicSkillsSync.js'
 import { continuityVaultRef } from '../continuity/storage.js'
-import type { Step } from './identityHubReducer.js'
+import type { Step } from './reducer.js'
 
-type UseIdentityHubContinuityArgs = {
+const WORKING_STATUS_STEPS = new Set<string>([
+  'menu',
+  'continuity-private',
+  'continuity-public',
+  'continuity-skills-tree',
+  'save-prompt',
+  'rebackup-confirm',
+  'recovery-refetch-confirm',
+  'continuity-overwrite-confirm',
+  'restore-recovery-input',
+  'restore-ens-input',
+  'restore-token-id-input',
+  'restore-select-token',
+])
+const WATCHED_VAULT_FILES = new Set<string>(['SOUL.md', 'MEMORY.md', 'agent-card.json'])
+
+type UseIdentityManagerContinuityArgs = {
   identity: EthagentIdentity | undefined
   step: Step
   setStep: (step: Step) => void
   handleStepError: (err: unknown, backStep: Step, softCancel?: Step) => void
 }
 
-export function useIdentityHubContinuity({
+export function useIdentityManagerContinuity({
   identity,
   step,
   setStep,
   handleStepError,
-}: UseIdentityHubContinuityArgs): {
+}: UseIdentityManagerContinuityArgs): {
   continuityReady: boolean
   setContinuityReady: (ready: boolean) => void
   workingStatus: ContinuityWorkingTreeStatus | null
@@ -60,36 +77,51 @@ export function useIdentityHubContinuity({
     return () => { cancelled = true }
   }, [identity, step.kind])
 
+  const computeStatus = useCallback(async (): Promise<ContinuityWorkingTreeStatus | null> => {
+    if (!identity) return null
+    try {
+      const [latest] = await listPublishedContinuitySnapshots(identity, 1)
+      return await continuityWorkingTreeStatus(identity, latest)
+    } catch {
+      return null
+    }
+  }, [identity])
+
+  const editorReturn = 'editorOpened' in step ? step.editorOpened : undefined
+
   useEffect(() => {
     let cancelled = false
     if (!identity) return
-    if (
-      step.kind !== 'menu'
-      && step.kind !== 'continuity-private'
-      && step.kind !== 'continuity-public'
-      && step.kind !== 'continuity-skills-tree'
-      && step.kind !== 'save-prompt'
-      && step.kind !== 'rebackup-confirm'
-    ) return
+    if (!WORKING_STATUS_STEPS.has(step.kind)) return
+    void computeStatus().then(status => { if (!cancelled) setWorkingStatus(status) })
+    return () => { cancelled = true }
+  }, [identity, step.kind, editorReturn, computeStatus])
 
-    const checkStatus = async () => {
-      try {
-        const [latest] = await listPublishedContinuitySnapshots(identity, 1)
-        const status = await continuityWorkingTreeStatus(identity, latest)
-        if (cancelled) return
-        setWorkingStatus(status)
-      } catch {
-        if (cancelled) return
-        setWorkingStatus(null)
-      }
+  useEffect(() => {
+    if (!identity) return
+    if (!WORKING_STATUS_STEPS.has(step.kind)) return
+    let cancelled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let watcher: FSWatcher | undefined
+    const schedule = (): void => {
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => {
+        void computeStatus().then(status => { if (!cancelled) setWorkingStatus(status) })
+      }, 200)
     }
-
-    void checkStatus()
-
+    try {
+      watcher = watch(continuityVaultRef(identity).dir, (_event, filename) => {
+        if (filename && !WATCHED_VAULT_FILES.has(String(filename))) return
+        schedule()
+      })
+      watcher.on('error', () => { try { watcher?.close() } catch {} })
+    } catch {}
     return () => {
       cancelled = true
+      if (timer) clearTimeout(timer)
+      try { watcher?.close() } catch {}
     }
-  }, [identity, step.kind])
+  }, [identity, step.kind, computeStatus])
 
   const requireReadyVault = async (): Promise<EthagentIdentity> => {
     if (!identity) throw new Error('No active identity')

package/src/identity/{hub/useIdentityHubController.ts → manager/useController.ts}

@@ -1,6 +1,5 @@
 import { useEffect, useReducer, useState } from 'react'
 import type { EthagentConfig, EthagentIdentity } from '../../storage/config.js'
-import { defaultModelFor } from '../../storage/config.js'
 import { setTokenIdentity } from '../../storage/identity.js'
 import type { BrowserWalletReady } from '../wallet/browserWallet.js'
 import { registryConfigFromConfig } from '../registry/registryConfig.js'
@@ -26,11 +25,11 @@ import type {
 } from './shared/effects/types.js'
 import { resolveVaultAddress } from './custody/transactions.js'
 import { useCustodyFlow } from './custody/useCustodyFlow.js'
-import { identityHubErrorView } from './shared/model/errors.js'
+import { identityManagerErrorView } from './shared/model/errors.js'
 import { readCustodyMode } from './custody/state.js'
 import { selectEnsStatus } from './ens/state.js'
-import { identityHubReducer, type ProfileUpdates, type Step } from './identityHubReducer.js'
-import type { IdentityHubProps } from './types.js'
+import { identityManagerReducer, type ProfileUpdates, type Step } from './reducer.js'
+import type { IdentityManagerProps } from './types.js'
 import {
   capitalizeFeedbackMessage,
   initialStepForAction,
@@ -40,20 +39,20 @@ import {
   preflightTokenOwnership,
   useAgentReconciliation,
 } from './shared/reconciliation/index.js'
-import { useIdentityHubContinuity } from './useIdentityHubContinuity.js'
-import { useIdentityHubSideEffects } from './useIdentityHubSideEffects.js'
+import { useIdentityManagerContinuity } from './useContinuity.js'
+import { useIdentityManagerSideEffects } from './useSideEffects.js'
 
-export function useIdentityHubController({
+export function useIdentityManagerController({
   mode,
   config,
   initialAction,
   onComplete,
   onConfigChange,
-}: IdentityHubProps) {
+}: IdentityManagerProps) {
   const [firstRunIdentity, setFirstRunIdentity] = useState<EthagentIdentity | null>(null)
   const identity = config?.identity ?? firstRunIdentity ?? undefined
   const { reconciliation, refresh: refreshReconciliation } = useAgentReconciliation(config ?? null)
-  const [step, dispatch] = useReducer(identityHubReducer, initialStepForAction(initialAction, config))
+  const [step, dispatch] = useReducer(identityManagerReducer, initialStepForAction(initialAction, config))
   const [walletSession, setWalletSession] = useState<BrowserWalletReady | null>(null)
   const [restoreProgress, setRestoreProgress] = useState<RestoreProgress | null>(null)
   const [tokenTransferProgress, setTokenTransferProgress] = useState<TokenTransferProgress | null>(null)
@@ -63,7 +62,7 @@ export function useIdentityHubController({
 
   const setStep = (s: Step) => dispatch({ type: 'setStep', step: s })
   const back = () => dispatch({ type: 'back', from: step })
-  const closeHub = () => onComplete(mode === 'first-run' ? { kind: 'skip' } : { kind: 'cancel' })
+  const closeManager = () => onComplete({ kind: 'cancel' })
 
   useEffect(() => { setWalletSession(null) }, [step.kind])
   useEffect(() => {
@@ -114,21 +113,24 @@ export function useIdentityHubController({
       const registry = registryFromIdentity(nextIdentity)
       const custodyMode = readCustodyMode(nextIdentity.state)
 
+      const seedConfig: EthagentConfig = {
+        version: 2,
+        firstSeenAt: new Date().toISOString(),
+        identity: { ...nextIdentity, source: 'erc8004' },
+        ...(registry
+          ? {
+              erc8004: {
+                chainId: registry.chainId,
+                rpcUrl: registry.rpcUrl,
+                identityRegistryAddress: registry.identityRegistryAddress,
+              },
+            }
+          : {}),
+      }
+      const persisted = await setTokenIdentity(seedConfig, nextIdentity)
+      onConfigChange?.(persisted)
+
       if (source === 'create' && custodyMode === 'advanced' && registry) {
-        const seedConfig: EthagentConfig = {
-          version: 1,
-          provider: 'llamacpp',
-          model: defaultModelFor('llamacpp'),
-          firstRunAt: new Date().toISOString(),
-          identity: { ...nextIdentity, source: 'erc8004' },
-          erc8004: {
-            chainId: registry.chainId,
-            rpcUrl: registry.rpcUrl,
-            identityRegistryAddress: registry.identityRegistryAddress,
-          },
-        }
-        const persisted = await setTokenIdentity(seedConfig, nextIdentity)
-        onConfigChange?.(persisted)
         const ownerAddress = (nextIdentity.ownerAddress ?? nextIdentity.address) as `0x${string}`
         const profileUpdates: ProfileUpdates = {
           custodyMode: 'advanced',
@@ -148,10 +150,10 @@ export function useIdentityHubController({
 
       const ensStatus = selectEnsStatus(nextIdentity)
       if (registry && ensStatus.kind === 'none') {
-        setStep({ kind: 'first-run-ens-prompt', identity: nextIdentity, registry })
+        setStep({ kind: 'first-run-ens-prompt', identity: nextIdentity, registry, origin: source === 'restore' ? 'restore' : 'create' })
         return
       }
-      onComplete({ kind: 'token', identity: nextIdentity })
+      setStep({ kind: 'menu' })
       return
     }
     const nextConfig = await setTokenIdentity(config, nextIdentity)
@@ -184,7 +186,8 @@ export function useIdentityHubController({
         return
       }
     }
-    onComplete({ kind: 'updated', config: nextConfig, message: capitalizeFeedbackMessage(message) })
+    onConfigChange?.(nextConfig)
+    setStep({ kind: 'operation-complete', message: capitalizeFeedbackMessage(message) })
   }
 
   const callbacks: EffectCallbacks = {
@@ -200,7 +203,7 @@ export function useIdentityHubController({
       setStep(softCancel)
       return
     }
-    setStep({ kind: 'error', error: identityHubErrorView(err), back: backStep })
+    setStep({ kind: 'error', error: identityManagerErrorView(err), back: backStep })
   }
 
   const guardOwnership = async (
@@ -290,14 +293,14 @@ export function useIdentityHubController({
     ...(onConfigChange ? { onConfigChange } : {}),
   })
 
-  const continuity = useIdentityHubContinuity({
+  const continuity = useIdentityManagerContinuity({
     identity,
     step,
     setStep,
     handleStepError,
   })
 
-  useIdentityHubSideEffects({
+  useIdentityManagerSideEffects({
     step,
     config,
     callbacks,
@@ -310,10 +313,10 @@ export function useIdentityHubController({
 
   const finishFirstRunIdentity = (): void => {
     if (!firstRunIdentity) {
-      onComplete({ kind: 'skip' })
+      onComplete({ kind: 'cancel' })
       return
     }
-    onComplete({ kind: 'token', identity: firstRunIdentity })
+    setStep({ kind: 'menu' })
   }
 
   const openEnsEdit = (backStep: Step): void => {
@@ -337,7 +340,7 @@ export function useIdentityHubController({
       handleStepError(new Error('no agent registry configured for this identity'), backStep)
       return
     }
-    setStep({ kind: 'edit-profile-name', identity, registry, returnTo: backStep })
+    setStep({ kind: 'edit-profile-menu', identity, registry, returnTo: backStep })
   }
 
   const openTokenTransferFlow = async (): Promise<void> => {
@@ -385,7 +388,7 @@ export function useIdentityHubController({
     workingStatus: continuity.workingStatus,
     setStep,
     back,
-    closeHub,
+    closeManager,
     setWalletSession,
     setJwtSaved,
     setCopyNotice,
@@ -406,4 +409,4 @@ export function useIdentityHubController({
   }
 }
 
-export type IdentityHubController = ReturnType<typeof useIdentityHubController>
+export type IdentityManagerController = ReturnType<typeof useIdentityManagerController>

package/src/identity/{hub/useIdentityHubSideEffects.ts → manager/useSideEffects.ts}

@@ -2,11 +2,12 @@ import { useEffect } from 'react'
 import type { EthagentConfig } from '../../storage/config.js'
 import { setTokenIdentity } from '../../storage/identity.js'
 import { isRegistrationPreflightError, pinataErrorText } from './shared/model/errors.js'
-import type { ProfileUpdates, Step } from './identityHubReducer.js'
+import type { ProfileUpdates, Step } from './reducer.js'
 import {
   runCreatePreflight,
   runCreateSigning,
 } from './create/effects.js'
+import { scanImportCandidates } from './create/importScan.js'
 import {
   runRebackupSigning,
 } from './continuity/effects.js'
@@ -36,7 +37,7 @@ type TriggerRebackup = (
   options?: { vaultAddress?: `0x${string}`; useVault?: boolean },
 ) => void
 
-type UseIdentityHubSideEffectsArgs = {
+type UseIdentityManagerSideEffectsArgs = {
   step: Step
   config: EthagentConfig | undefined
   callbacks: EffectCallbacks
@@ -47,7 +48,7 @@ type UseIdentityHubSideEffectsArgs = {
   onConfigChange?: (config: EthagentConfig) => void
 }
 
-export function useIdentityHubSideEffects({
+export function useIdentityManagerSideEffects({
   step,
   config,
   callbacks,
@@ -56,12 +57,45 @@ export function useIdentityHubSideEffects({
   triggerRebackup,
   setContinuityReady,
   onConfigChange,
-}: UseIdentityHubSideEffectsArgs): void {
+}: UseIdentityManagerSideEffectsArgs): void {
   useEffect(() => {
     if (step.kind !== 'rebackup-start') return
     triggerRebackup(step.back)
   }, [step])
 
+  useEffect(() => {
+    if (step.kind !== 'create-import') return
+    if (step.candidates !== undefined) return
+    let cancelled = false
+    const toPreflight: Step = {
+      kind: 'create-preflight',
+      name: step.name,
+      description: step.description,
+      ...(step.network ? { network: step.network } : {}),
+      custodyMode: step.custodyMode,
+    }
+    scanImportCandidates()
+      .then(candidates => {
+        if (cancelled) return
+        if (candidates.length === 0) {
+          setStep(toPreflight)
+          return
+        }
+        setStep({
+          kind: 'create-import',
+          name: step.name,
+          description: step.description,
+          ...(step.network ? { network: step.network } : {}),
+          custodyMode: step.custodyMode,
+          candidates,
+        })
+      })
+      .catch(() => {
+        if (!cancelled) setStep(toPreflight)
+      })
+    return () => { cancelled = true }
+  }, [step])
+
   useEffect(() => {
     if (step.kind !== 'create-preflight') return
     let cancelled = false
@@ -94,6 +128,7 @@ export function useIdentityHubSideEffects({
             custodyMode: step.custodyMode,
             error: pinataErrorText(err),
             pinataJwt: step.pinataJwt,
+            ...(step.importNotes ? { importNotes: step.importNotes } : {}),
           })
           return
         }
@@ -120,6 +155,7 @@ export function useIdentityHubSideEffects({
             profileUpdates: step.profileUpdates,
             returnTo: step.returnTo,
             walletPurpose: step.walletPurpose,
+            ...(step.vaultAddress ? { vaultAddress: step.vaultAddress } : {}),
           })
           return
         }

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

@@ -5,7 +5,10 @@ import { isAgentInVault } from '../vault.js'
 import { ERC8004_ABI, TRANSFER_EVENT } from './abi.js'
 import {
   SUPPORTED_ERC8004_CHAINS,
+  chainSortIndex,
   erc8004ConfigForSupportedChain,
+  logBlockRangeForChain,
+  minLogBlockRangeForChain,
   supportedErc8004ChainForId,
 } from './chains.js'
 import { createErc8004PublicClient } from './client.js'
@@ -492,20 +495,3 @@ function blockRangesBackwards(
   }
   return ranges
 }
-
-function logBlockRangeForChain(chainId: number): bigint {
-  const chain = supportedErc8004ChainForId(chainId)
-  if (!chain) return 10_000n
-  return chain.logBlockRange
-}
-
-function minLogBlockRangeForChain(chainId: number): bigint {
-  const chain = supportedErc8004ChainForId(chainId)
-  if (!chain) return 2_000n
-  return chain.kind === 'l2' ? chain.logBlockRange : chain.logBlockRange / 2n || 1n
-}
-
-function chainSortIndex(chainId: number): number {
-  const index = SUPPORTED_ERC8004_CHAINS.findIndex(chain => chain.chainId === chainId)
-  return index === -1 ? Number.MAX_SAFE_INTEGER : index
-}

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

@@ -12,7 +12,7 @@ export function uniqueStrings(values: string[]): string[] {
 export function cleanRpcError(err: unknown): string {
   const message = err instanceof Error ? err.message : String(err)
   return message
-    .replace(/s+/g, ' ')
+    .replace(/\s+/g, ' ')
     .slice(0, 220)
 }
 

package/src/identity/storage/ipfs.ts

@@ -15,6 +15,26 @@ type IpfsOptions = {
   pinataJwt?: string
 }
 
+export class PinataUploadError extends Error {
+  readonly status: number
+  readonly statusText: string
+  constructor(status: number, statusText: string) {
+    super(pinataUploadErrorMessage(status, statusText))
+    this.name = 'PinataUploadError'
+    this.status = status
+    this.statusText = statusText
+  }
+}
+
+function pinataUploadErrorMessage(status: number, statusText: string): string {
+  const code = statusText ? `${status} ${statusText}` : String(status)
+  if (status === 401) return `Pinata rejected the upload (${code}): the storage credential is invalid or expired.`
+  if (status === 403) return `Pinata refused the upload (${code}): your account is likely at its file or storage limit.`
+  if (status === 429) return `Pinata is rate-limiting uploads (${code}): too many requests in a short window.`
+  if (status === 413) return `Pinata rejected the upload (${code}): the snapshot is larger than your plan allows.`
+  return `IPFS upload failed: ${code}.`
+}
+
 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) ?? []
@@ -142,7 +162,7 @@ async function addFileToPinata(
     },
     body,
   })
-  if (!response.ok) throw new Error(`IPFS upload failed: ${response.status} ${response.statusText}`)
+  if (!response.ok) throw new PinataUploadError(response.status, response.statusText)
   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')

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

@@ -4,14 +4,22 @@ import { loadWalletPageSource } from './walletPageSource.js'
 
 const WALLET_HTML = loadWalletHtml()
 
-export function walletPage(title: string, sessionToken: string, payload: Record<string, unknown>): string {
+function injectWalletConfig(shell: string, title: string, sessionToken: string, payload: Record<string, unknown>): string {
   const config = JSON.stringify({ sessionToken, ...normalizeWalletPayloadPurpose(payload) }).replaceAll('<', '\\u003c')
   const injection = `<script>window.__WALLET_CONFIG__ = ${config};</script>`
-  return WALLET_HTML
+  return shell
     .replace(/<title>.*?<\/title>/, `<title>${escapeHtml(title)}</title>`)
     .replace('<head>', `<head>\n  ${injection}`)
 }
 
+export function walletPage(title: string, sessionToken: string, payload: Record<string, unknown>): string {
+  return injectWalletConfig(WALLET_HTML, title, sessionToken, payload)
+}
+
+export function walletPageFresh(title: string, sessionToken: string, payload: Record<string, unknown>): string {
+  return injectWalletConfig(loadWalletHtml(), title, sessionToken, payload)
+}
+
 export function __testWalletPage(title: string, sessionToken: string, payload: Record<string, unknown>): string {
   return walletPage(title, sessionToken, payload)
 }