> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/prd-shared/onboarding-workflow.md).

# Onboarding Workflow

> **Referenced by**: [vault/03-custody.md](/docs/gotts-vaults/vault/03-custody.md), [mcp-server/10-wallets.md](/docs/gotts-safe-mcp-server/mcp-server/10-wallets.md), [agents/07-agents-infra.md](/docs/agents/agents/07-agents-infra.md) | **Last Updated**: 2026-02-14
>
> End-to-end guide for setting up an agent wallet, registering ERC-8004 identity, configuring guardian protection, funding, and vault participation. Covers three onboarding paths for three agent profiles.

***

## Step 0: Deploy MCP Server (Prerequisite)

Before any onboarding path, the MCP server must be running and accessible. The MCP server is the execution layer -- it reads credentials, signs transactions, and exposes the tools that agents use for wallet operations, identity registration, and vault participation. Without a running MCP server, none of the steps below can execute.

**Local development** (no deployment needed):

```bash
cd packages/safe
cp .env.example .env   # Edit with ALCHEMY_API_KEY and wallet config
pnpm dev               # Runs stdio server, auto-discovered by Claude Code / Cursor
```

**Production deployment** (one command):

```bash
pnpm setup:production   # Interactive: creates wallet, deploys to Fly.io, outputs client config
```

The setup script creates a Privy wallet, generates `.env`, deploys to Fly.io (\~$5/month), and outputs the client configuration JSON for Claude Code or Cursor. Total time: \~7 minutes. See [mcp-server/14-deployment.md](/docs/gotts-safe-mcp-server/mcp-server/14-deployment.md) for the full deployment guide, platform comparison, and security hardening checklist.

**Verify**: After deployment, run the `check_setup_health` MCP tool. It should return `overall: ready` (or `degraded` with specific remediation steps).

***

## Credential Architecture (Read First)

Before following any onboarding path, understand the credential model: **the LLM agent never holds keys.** The operator (human) provisions the wallet, configures credentials, and the MCP server process uses them. The agent is stateless with respect to wallet access.

For the full explanation -- including who holds what, failure/recovery scenarios, and credential rotation procedures -- see [**credential-architecture.md**](/docs/prd-shared/credential-architecture.md).

**Key takeaway**: Choose a wallet provider that can **sign arbitrary transactions** (required for vault contracts). Privy (recommended) supports this. Local key is available for development only.

***

## Canonical Onboarding Reference

The **canonical onboarding definitions** live in [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) Section "Canonical Onboarding (Normative)". This PRD defines exactly three persona-specific journeys:

* **Vault Participant** (2 steps): Onboard via `OnboardRouter` + Join via deposit or share purchase
* **Vault Creator** (3 steps): Onboard + Deploy vault template + Configure strategy
* **Vault Manager / Strategist** (2 steps): Onboard + Bind to existing vault

All paths, variants, and infrastructure-specific flows in this document are *explanatory detail* for the canonical definitions above.

### Normative Onboarding Flow

```mermaid
flowchart TD
  Start(["Start"]) --> Persona{"Choose persona"}
  Persona -->|Participant| P1["Select chain"]
  Persona -->|Manager| M1["Select chain + vault"]
  Persona -->|Creator| C1["Select chain + template"]

  P1 --> Cap{"Load ChainCapabilities"}
  M1 --> Cap
  C1 --> Cap

  Cap -->|"v4SharePools=on"| Market["Enable share pool UI"]
  Cap -->|"v4SharePools=off"| NoMarket["Deposit-only UI"]

  Cap --> Wallet["Create/attach smart wallet"]
  Wallet --> Policy["Apply policy preset"]
  Policy --> Identity["Register identity + guardian"]
  Identity --> JoinMethod{"Join method"}

  JoinMethod -->|Deposit| Deposit["Simulate then deposit"]
  JoinMethod -->|"Buy shares"| Buy["Quote then buy shares"]

  Deposit --> Monitor["Start monitoring dashboard"]
  Buy --> Monitor
  Monitor --> Done(["Done"])
```

### Agent Management Flow (post-onboarding)

```mermaid
sequenceDiagram
  participant O as Operator
  participant W as SmartWallet
  participant S as MCPServer
  participant V as VaultProtocol

  O->>S: Run setup wizard / apply preset
  S->>W: Configure session keys + limits
  O->>S: Request capability upgrade (Manager to Creator)
  S->>V: Simulate capability change tx
  alt within safe envelope
    S->>V: Execute immediately
  else requires delay / governance
    S->>V: Schedule via timelock + publish announcement
  end
  O->>S: Emergency pause
  S->>V: Execute pause path (fast lane)
```

***

## Overview

Every agent interacting with Gotts Vaults needs three things: a **wallet** (to sign arbitrary transactions), an **identity** (ERC-8004 registration), and **guardian protection** (to prevent identity theft). This document specifies the detailed onboarding workflow variants that implement the canonical flows above.

### Recommended: 2-Step Atomic Onboarding

The fastest path implements the **Vault Participant** canonical flow by collapsing the entire onboarding into two user-facing steps:

1. **Create wallet + register identity** -- The `OnboardRouter` contract batches wallet creation (via ERC-4337 counterfactual deployment), ERC-8004 identity registration, Permit2 approval, and reputation enrollment into a single gasless UserOperation. A paymaster sponsors gas on Base.
2. **Select vault template + deposit** -- The agent selects a vault (or the CLI picks the best Simple Yield vault automatically) and deposits in one transaction.

This is the default path in the install wizard (`npx @gotts.ai setup --intent vault-participant`) and the SDK's `onboardAndDeposit()` function. See [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) for the full canonical flow and detailed code examples.

### Explicit Paths (For Manual Control)

For operators who want step-by-step control, three manual paths are available (these are *explanatory variants* of the canonical flows):

| Profile                          | Description                                                      | Starting State          | Recommended Path                                        |
| -------------------------------- | ---------------------------------------------------------------- | ----------------------- | ------------------------------------------------------- |
| **New Agent**                    | No wallet, no identity, starting from scratch                    | Nothing                 | Path A (Automated) or Path B (Manual)                   |
| **Existing Wallet, No Identity** | Has a wallet (EOA or smart account) but no ERC-8004 registration | Wallet exists           | Path B (Manual) -- register identity on existing wallet |
| **Existing ERC-8004 Agent**      | Already registered ERC-8004, possibly on an EOA                  | Wallet + identity exist | Path C (Migration) -- upgrade to protected setup        |

### Onboarding Decision Tree

```mermaid
flowchart TD
    Start[Agent wants to participate] --> HasWallet{Has wallet?}

    HasWallet -->|No| HasPreference{Security preference?}
    HasPreference -->|Quick start| PathA_Auto[Path A: Automated Onboarding]
    HasPreference -->|Full control| PathB_Manual[Path B: Manual Setup]

    HasWallet -->|Yes| HasIdentity{Has ERC-8004 identity?}

    HasIdentity -->|No| WalletType{Wallet type?}
    WalletType -->|Smart account| PathB_Register[Path B: Register identity on existing wallet]
    WalletType -->|EOA| PathB_Upgrade[Path B: Upgrade EOA first, then register]

    HasIdentity -->|Yes| GuardianEnabled{Guardian enabled?}
    GuardianEnabled -->|Yes| SmartWallet{Identity in smart wallet?}
    SmartWallet -->|Yes| Ready[Ready -- proceed to vault operations]
    SmartWallet -->|No| PathC_Migrate[Path C: Migrate identity to smart wallet]
    GuardianEnabled -->|No| EnableGuardian[Enable guardian, then check wallet type]
    EnableGuardian --> SmartWallet
```

***

## Path A: Automated Onboarding (Recommended)

Single-command onboarding via the `self-funding-setup` skill or the `OnboardRouter.sol` contract. All steps execute atomically -- if any step fails, the entire operation reverts.

### Prerequisites

* An operator address (can be an EOA) with funds for gas (or a paymaster for gasless execution)
* USDC for initial vault deposit (optional)

### Steps

**Step 1: Provision Smart Contract Wallet**

The system provisions an ERC-4337 smart account via the configured wallet provider:

| Provider                | Setup Time  | Gas Cost                         | Best For                                       |
| ----------------------- | ----------- | -------------------------------- | ---------------------------------------------- |
| **Privy** (recommended) | \~3 minutes | Standard gas (or sponsored)      | Production agents, OpenClaw, granular policies |
| Safe (1-of-1)           | 1-3 minutes | Higher gas (contract deployment) | Maximum on-chain enforcement                   |

The wallet address is computed deterministically via CREATE2 before deployment. This enables **counterfactual onboarding**: the wallet can receive USDC at its future address before it even exists on-chain.

**Step 2: Register ERC-8004 Identity**

**Recommended path: `@gotts.ai/wallet`** (wraps Agent0 SDK with three-tier fallback). The `registerAgent()` function handles IPFS upload, structured metadata, and on-chain registration with automatic fallback:

```typescript
import { GottsWallet, registerAgent } from "@gotts.ai/wallet";

const wallet = new GottsWallet({
  mode: "privy",
  appId,
  appSecret,
  walletId,
  authPrivateKey,
});
const result = await registerAgent(wallet, {
  name: "My Vault Manager",
  description: "Autonomous USDC yield optimizer on Base",
  role: "vault_manager",
  mcpEndpoint: "https://my-agent.fly.dev/mcp",
});
// result.agentId = "42"
// result.registrationMethod = "agent0-ipfs"
// result.agentURI = "ipfs://Qm..."
```

**Three-tier registration fallback** (see [erc8004-integration.md](/docs/prd-shared/erc8004-integration.md) for the full spec):

1. **Tier 1** (default): Agent0 SDK + Gotts IPFS proxy (`GOTTS_IPFS_MODE=gotts`). Full discoverability, zero IPFS config needed from the operator.
2. **Tier 2**: Agent0 SDK + inline metadata URI. No IPFS needed, reduced discoverability.
3. **Tier 3**: Direct contract call via viem. No Agent0 SDK dependency, minimal metadata.

The function falls back automatically -- if `agent0-sdk` is not installed, it uses Tier 3. If IPFS proxy is unreachable, it falls back from Tier 1 to Tier 2.

**EIP-1193 bridge**: The `createEIP1193Provider(wallet)` function bridges the `GottsWallet` to the Agent0 SDK's `walletProvider` config. Signing operations route to the wallet backend (Privy TEE or local signer); all other RPC calls proxy to the configured chain RPC URL. See [erc8004-integration.md](/docs/prd-shared/erc8004-integration.md) Section 1 for the method routing table.

**Gas strategy**: Registration uses a three-tier gas resolution: paymaster-sponsored on Base mainnet (zero ETH), testnet faucet on Sepolia/Base Sepolia (automatic), or manual funding as fallback. See [erc8004-integration.md](/docs/prd-shared/erc8004-integration.md) Section 6.

**Fallback path: direct contract call (Tier 3)**. For non-Privy setups or when Agent0 SDK is not installed, the system mints via direct contract interaction:

```
identityRegistry.register(handle, metadataURI, interfaceType)
```

* `handle`: Unique, human-readable identifier (e.g., "my-trading-agent")
* `metadataURI`: IPFS or inline `data:` URI pointing to the agent's AgentCard JSON
* `interfaceType`: 1 (autonomous agent)

The identity NFT is minted directly to the smart contract wallet address. It never touches an EOA.

**Step 3: Enable Guardian Protection**

Immediately after minting, the system enables guardian protection on the identity NFT:

```
identityGuardian.enableGuardian(tokenId)
```

Guardian is enabled by default on new mints, but this step explicitly verifies the guardian state. The system also configures:

* Guardian addresses (operator address + optional additional guardians)
* Monitoring alerts for `TransferRequested` events on this token ID
* Safe Transaction Guard blocking identity transfer selectors (if using Safe wallet)

**Step 3.5: Optional -- Register ENS Name**

If the agent wants a human-readable on-chain identity (e.g., `my-trading-agent.eth`), the system registers an ENS name via the `ens-registrar` agent:

1. Check name availability via the ETH Registrar Controller
2. Submit a commitment hash (commit step of the commit/reveal flow)
3. Wait 60+ seconds for commit maturity (ENS front-running protection)
4. Execute registration with payment (register step)
5. Set text records: `ai.erc8004.agentId` linking to the identity from Step 2, plus description and other metadata
6. Set reverse record so the agent's address resolves to its ENS name

This step uses ETH on Ethereum mainnet (same chain as ERC-8004 registration in Step 2). Budget an additional \~0.01 ETH for ENS registration + gas for a 5+ character name. The ENS name and ERC-8004 identity are linked via text records, creating a unified, discoverable identity.

**Note**: ENS names require annual renewal (unlike permanent ERC-8004 identity NFTs). The system reports the renewal date and estimated cost.

**Step 4: Configure Wallet Policy**

Apply the appropriate wallet policy template based on the agent's intended role:

| Role              | Policy Template                  | Key Restrictions                                                   |
| ----------------- | -------------------------------- | ------------------------------------------------------------------ |
| Vault Participant | `vault-participant-simple-yield` | Only vault deposit/withdraw + USDC approve + identity registration |
| Vault Manager     | `vault-manager-proxy-enhanced`   | Only `announce()` on proxy contract                                |
| General Trading   | `defi-trading`                   | Uniswap Router + PoolManager                                       |

See [vault/03-custody.md](/docs/gotts-vaults/vault/03-custody.md) Section 3 for full policy specifications.

**Step 5: Fund Wallet**

Transfer gas tokens to the wallet on each required chain:

| Chain                            | Recommended Initial Funding | Estimated Operations                                                |
| -------------------------------- | --------------------------- | ------------------------------------------------------------------- |
| Ethereum (ERC-8004 registration) | 0.01 ETH                    | Identity registration only (add \~0.01 ETH if registering ENS name) |
| Base (primary operations)        | 0.005 ETH                   | \~100 vault operations                                              |
| Arbitrum (if needed)             | 0.002 ETH                   | \~100 vault operations                                              |

For **gasless onboarding on Base**: A paymaster sponsors the entire UserOp, including wallet deployment, identity registration, and first deposit. Zero ETH required.

**Step 6: Optional -- First Vault Deposit**

If the agent has USDC, the system can execute an initial deposit in the same atomic operation:

```
vault.deposit(agentId, depositAmount)
```

### Atomic Execution via OnboardRouter

When using ERC-4337, all six steps collapse into a single UserOperation:

```
OnboardRouter.onboardAndDeposit({
    handle: "my-trading-agent",
    metadataURI: "ipfs://Qm...",
    interfaceType: 1,
    vault: 0xVault...,
    depositAmount: 1000e6,  // 1000 USDC
    baseAsset: USDC_ADDRESS,
    referrerAgentId: 0
})
```

Internal flow: register identity -> approve Permit2 -> enroll reputation -> enable guardian -> deposit. All atomic. See [vault/06-contracts.md](/docs/gotts-vaults/vault/06-contracts.md) Section 10.15 for the contract specification.

### Skill Invocation

```
"Set up my agent to be self-funding on Base"
"Set up my agent to be self-funding on Base with ENS name my-trading-agent"
```

This activates the `self-funding-setup` skill, which orchestrates the `wallet-provisioner`, `identity-verifier`, and optionally `ens-registrar` agents to execute the full pipeline. ENS registration is triggered by including "with ENS" or specifying a name.

***

## Path B: Manual Setup

Step-by-step onboarding for operators who want full control over each stage. Each step is independently executable and verifiable.

### Step 1: Choose and Provision Wallet

**If you don't have a wallet yet:**

Select a wallet provider based on your security requirements (see [mcp-server/10-wallets.md](/docs/gotts-safe-mcp-server/mcp-server/10-wallets.md) for the full comparison):

```bash
# Option 1: Privy (via MCP tool)
# Configure PRIVY_APP_ID and PRIVY_APP_SECRET in environment
# Call mcp__uniswap__createWallet with provider: "privy"

# Option 2: Safe (maximum security)
# Deploy a Safe via safe.global, configure as 1-of-1 with your signer
```

**If you have an existing EOA:**

Upgrade to a smart account to enable key rotation without identity loss:

* **EIP-7702 (Pectra upgrade)**: Existing EOAs can temporarily behave as smart accounts. This is the lowest-friction upgrade path -- no new address needed.
* **Safe 1-of-1**: Deploy a Safe with your EOA as the sole signer. Transfer assets to the Safe address. The Safe address becomes your permanent identity address.
* **ZeroDev Kernel**: Deploy an ERC-4337 account controlled by your EOA. Session keys provide scoped permissions.

**Critical recommendation**: Identity NFTs should reside in smart contract wallets, not raw EOAs. Smart contract wallets enable key rotation without moving the NFT, which preserves all reputation. See [vault/03-custody.md](/docs/gotts-vaults/vault/03-custody.md) Section 8.3.

### Step 2: Register ERC-8004 Identity

Register your agent on the ERC-8004 Identity Registry (Ethereum mainnet):

1. **Prepare AgentCard**: Create an AgentCard JSON file following the ERC-8004 schema. Host it on IPFS or HTTPS. The AgentCard includes:
   * Agent name, description, and capabilities
   * Supported interfaces (MCP tools, API endpoints)
   * Operator information
   * Contact and support URIs
2. **Mint Identity**: Call `identityRegistry.register()` from your smart contract wallet:

   ```
   register(handle, metadataURI, interfaceType)
   ```

   This mints an ERC-721 token to your wallet and returns an `agentId`.
3. **Verify Registration**: Confirm via `identityRegistry.getAgentWallet(agentId)` that it returns your wallet address.

**Gas requirement**: \~0.01 ETH on Ethereum mainnet for the registration transaction.

### Step 3: Enable Guardian Protection

After registration, configure the IdentityGuardian:

1. **Enable Guardian** (default for new mints, verify explicitly):

   ```
   identityGuardian.enableGuardian(tokenId)
   ```
2. **Designate Guardian Addresses**: Grant `GUARDIAN_ROLE` to trusted addresses:
   * Your operator's personal wallet (for manual veto)
   * A monitoring bot address (for automated veto)
   * Optionally, a trusted third party (for social recovery)
3. **Configure Monitoring**: Set up alerts for your token ID:
   * Watch for `TransferRequested` events on the IdentityGuardian contract
   * Watch for `Transfer` events on the Identity Registry targeting your token ID
   * Configure Telegram/Discord/PagerDuty notifications
4. **Install Safe Transaction Guard** (if using Safe wallet):
   * Deploy or configure a guard that blocks `transferFrom` and `safeTransferFrom` selectors for the Identity Registry contract address
   * Also install `IModuleGuard` (Safe v1.5+) to prevent module-initiated transfers
5. **Optional -- Burn Transfer Fuse**: For agents at Trusted tier (reputation >= 100) who want permanent identity binding:

   ```
   identityGuardian.burnTransferFuse(tokenId)
   ```

   **Warning**: This is irreversible. The identity can never be transferred after burning the fuse.

### Step 3.5: Optional -- Register ENS Name

Give your agent a human-readable on-chain identity via ENS. This step uses the `register-ens-name` skill or can be performed manually.

1. **Choose a name**: Select a name for your agent (e.g., `my-trading-agent`). Names must be at least 3 characters, lowercase alphanumeric with hyphens. 5+ character names cost \~$5/year; shorter names cost significantly more.
2. **Check availability**: Verify the name is not already registered. Use the ENS app (app.ens.domains) or query the ETH Registrar Controller directly.
3. **Commit**: Submit a commitment hash to the ETH Registrar Controller:

   ```
   controller.commit(commitmentHash)
   ```

   The commitment hash is generated from: name, owner, duration, secret, resolver, data, reverseRecord, ownerControlledFuses.
4. **Wait 60+ seconds**: The ENS protocol enforces a minimum 60-second wait between commit and register to prevent front-running. Maximum wait: 24 hours (commitment expires).
5. **Register**: Execute the registration with payment:

   ```
   controller.register{value: fee}(name, owner, duration, secret, resolver, data, reverseRecord, ownerControlledFuses)
   ```
6. **Set text records**: Configure the resolver with agent metadata:
   * `ai.erc8004.agentId`: Your ERC-8004 agent ID from Step 2 (links ENS to on-chain identity)
   * `description`: Agent description
   * `url`: Agent endpoint or documentation URL
7. **Set reverse record**: Call `reverseRegistrar.setName(name)` from your agent wallet so your address resolves to the ENS name.
8. **Verify**: Confirm forward resolution (`my-trading-agent.eth` -> your address) and reverse resolution (your address -> `my-trading-agent.eth`).

**Gas requirement**: \~0.01 ETH on Ethereum mainnet for all ENS transactions (commit + register + records + reverse). This is on top of the ERC-8004 registration gas.

**Note**: ENS names expire and require annual renewal. Set a reminder for the expiry date.

### Step 4: Configure Wallet Policies

Apply security policies to restrict what the wallet can do:

1. **Select policy template**: Choose from the templates in [vault/03-custody.md](/docs/gotts-vaults/vault/03-custody.md) Section 3
2. **Configure spending limits**: Per-transaction, per-session, and daily caps
3. **Set contract allowlist**: Only the contracts your agent needs to interact with
4. **Set method allowlist**: Only the functions your agent needs to call
5. **Configure rate limits**: Maximum operations per time window

For vault managers, use the proxy-enhanced policy (Section 3.4) where the wallet can only call `announce()` on the proxy contract.

### Step 5: Fund Wallet

1. **Estimate gas needs**: Calculate based on expected operations per chain
2. **Transfer native tokens**: Send ETH to your wallet on each required chain
3. **Verify balances**: Confirm arrival via `mcp__uniswap__get_agent_balance`
4. **Transfer USDC** (if depositing into vaults): Send USDC to your wallet on the vault's chain

### Step 6: Validate Setup

Run the complete readiness checklist before going live:

* [ ] **Read test**: Call `mcp__uniswap__get_agent_balance` to verify wallet connectivity
* [ ] **Simulation test**: Dry-run a vault deposit simulation to confirm signing works
* [ ] **Policy enforcement test**: Attempt an unauthorized operation and verify it is rejected
* [ ] **Identity test**: Call `mcp__uniswap__query_reputation` for your agent ID to verify registration
* [ ] **Guardian test**: Verify `identityGuardian.guardianEnabled(tokenId)` returns true
* [ ] **Guard test**: If using Safe, verify the Transaction Guard rejects identity transfer attempts

***

## Path C: Migration for Existing ERC-8004 Agents

For agents that already have an ERC-8004 identity registered -- typically on an EOA before the guardian system existed. The goal is to upgrade to a protected setup without losing reputation (or minimizing reputation loss).

### Scenario 1: EOA Is Not Compromised (Recommended: EIP-7702 Upgrade)

If the agent's EOA private key is secure, the best path is to **upgrade the EOA in-place** without transferring the identity NFT:

1. **Upgrade via EIP-7702**: The Pectra upgrade (live May 2025) allows EOAs to temporarily behave as smart accounts. Set the EOA's code to point to a smart account implementation (ZeroDev Kernel, Safe via EIP-7702 adapter).
2. **Configure session keys**: After upgrade, the EOA supports session keys. Create operational session keys for daily agent use. Store the original EOA key as the sudo/recovery key in cold storage.
3. **Enable guardian**: Now that the wallet behaves as a smart account, enable the IdentityGuardian on the identity NFT.
4. **Install Transaction Guard**: Configure guards to block identity transfer selectors.

**Reputation impact**: None. The wallet address does not change. No `Transfer` event is emitted. Full reputation is preserved.

### Scenario 2: EOA Is Not Compromised (Full Migration)

If EIP-7702 is not suitable (e.g., the agent needs a native Safe or ERC-4337 wallet):

1. **Deploy new smart contract wallet**: Provision via Privy/Safe
2. **Enable guardian on identity NFT** (before transfer): Call `identityGuardian.enableGuardian(tokenId)` from the EOA
3. **Request transfer**: Call `DANGER__requestTransfer(tokenId, newWalletAddress)` from the EOA
4. **Wait 7-day cooldown**: The identity remains functional during this period. Monitor for any unauthorized cancel attempts.
5. **Execute transfer**: After cooldown, call `executeTransfer(tokenId)` -- identity moves to new wallet
6. **Re-enable guardian on new wallet**: Verify guardian protection is active
7. **Configure wallet policies and guards**: Apply the security setup from Path B, Steps 3-4

**Reputation impact**: 30-day linear decay. Effective reputation drops to near-zero and recovers over 30 days. Plan for reduced vault access during the recovery period.

**Mitigation**: If the agent is at Trusted or Sovereign tier, consider completing all pending vault operations before initiating the transfer. During the 30-day recovery, the agent will be limited to Basic-tier deposit caps ($10,000).

### Scenario 3: EOA May Be Compromised

If there is any suspicion that the EOA's private key has been leaked or exposed:

1. **Freeze credential immediately**: Have a guardian call `identityGuardian.freezeCredential(tokenId)` to revoke all vault access
2. **Monitor for unauthorized transfers**: Watch for `Transfer` events on the identity NFT
3. **Request governance reissuance**: If the key is confirmed compromised, submit a governance proposal to reissue the identity via `reissueIdentity(oldTokenId, newOwner, handle, metadataURI)`
4. **Reissuance outcome**: New token minted to the new wallet with 50% of base reputation preserved. The old token is burned or permanently frozen.

**Reputation impact**: 50% permanent loss on reissuance. This reflects the cost of key compromise even in legitimate recovery.

### Migration Decision Matrix

| Current State                             | Recommended Action                       | Reputation Impact  | Timeline                               |
| ----------------------------------------- | ---------------------------------------- | ------------------ | -------------------------------------- |
| EOA, key secure, EIP-7702 supported       | Upgrade EOA in-place                     | None               | Same day                               |
| EOA, key secure, need native smart wallet | Guardian-protected transfer              | 30-day decay       | 7 days (cooldown) + 30 days (recovery) |
| EOA, key possibly compromised             | Freeze + governance reissuance           | 50% permanent loss | Days-weeks (governance)                |
| Smart wallet, no guardian                 | Enable guardian, install guards          | None               | Same day                               |
| Smart wallet, guardian enabled, no guards | Install Transaction Guard + Module Guard | None               | Same day                               |

***

## Post-Onboarding Checklist

After completing any onboarding path, verify every item from the Production Security Checklist in [vault/10-safety.md](/docs/gotts-vaults/vault/10-safety.md):

**MCP Server**:

* [ ] MCP server is deployed and accessible (Fly.io, Railway, Docker, or local)
* [ ] `check_setup_health` returns `overall: ready`
* [ ] Streamable HTTP transport with TLS (production) or stdio (local development)
* [ ] Secrets stored in platform secret manager (Fly.io secrets, Doppler), not `.env` files in production
* [ ] Pino log redaction configured for all secret paths

**Identity Security**:

* [ ] Identity NFT is in a smart contract wallet (not EOA)
* [ ] Guardian is enabled
* [ ] Transaction Guard blocks identity transfers
* [ ] Monitoring alerts are configured for Transfer and TransferRequested events
* [ ] At least one guardian address besides the operator is configured
* [ ] Sudo key is in cold storage

**Wallet Security**:

* [ ] Wallet policy is configured with contract and method allowlists
* [ ] Spending limits are set (per-tx, per-session, daily)
* [ ] Keys are TEE-isolated (not raw private keys in environment variables)
* [ ] Rate limits are configured

**Operational Readiness**:

* [ ] Wallet is funded on all required chains
* [ ] Read test passed (can query balances)
* [ ] Simulation test passed (can sign transactions)
* [ ] Policy enforcement test passed (unauthorized operations are rejected)
* [ ] Identity verification test passed (ERC-8004 registration confirmed)

**Proxy Security** (if using time-delayed proxy):

* [ ] Proxy contract deployed and configured
* [ ] Cancel authority is a separate key from owner and agent
* [ ] Monitoring bot is running with redundant RPC connections
* [ ] Auto-cancel rules configured for identity-related announcements
* [ ] Variable delay schedule configured per risk tier

***

## Frequently Asked Questions

**Q: Do I need ETH on Ethereum mainnet?** A: Yes, for ERC-8004 registration (the Identity Registry is on Ethereum L1). However, if using a paymaster on Base, the registration step can be sponsored. All vault operations happen on L2 (Base).

**Q: Can I use the same wallet address across multiple chains?** A: Yes. Smart contract wallets (ERC-4337, Safe) produce deterministic addresses via CREATE2. The same address works across all supported chains. Your identity NFT lives on Ethereum L1, but cross-chain identity resolution allows vault participation on any chain.

**Q: What happens if I lose all my keys?** A: If you configured social recovery (recommended), your guardians can initiate key rotation after a 48-hour delay. If you have no guardians and no backup keys, the identity and all associated reputation are lost. This is why the onboarding workflow strongly recommends configuring at least 2-of-3 guardians.

**Q: Can I transfer my identity to a different agent?** A: Technically yes (with the 7-day guardian cooldown), but the identity's effective reputation will decay to near-zero and take 30 days to recover. Identities with 2+ transfers in 90 days are permanently downgraded to Basic tier until the window clears. The system is designed to make identity trading uneconomical.

**Q: I already have an ERC-8004 identity on an EOA. Is my identity at risk?** A: Yes -- EOA keys can be stolen, and the identity NFT can be transferred in a single transaction with no delay. We strongly recommend migrating to a smart contract wallet (see Path C). The EIP-7702 upgrade path preserves full reputation with no transfer required.

**Q: Should I register an ENS name for my agent?** A: It's optional but recommended for agents that interact with other agents or humans. An ENS name (e.g., `my-agent.eth`) makes your agent discoverable and memorable. It also provides reverse resolution -- when others encounter your agent's address, they see the name instead of a hex string. Cost is \~$5/year for 5+ character names plus \~0.01 ETH in gas. Use the `register-ens-name` skill or include "with ENS" in the `self-funding-setup` flow.

**Q: What happens if my ENS name expires?** A: After expiry, there is a 90-day grace period during which only the previous owner can renew. After that, the name becomes available for anyone to register. Losing an ENS name does not affect your ERC-8004 identity or vault access -- those are based on your wallet address, not the ENS name. However, reverse resolution will stop working and other agents will no longer be able to find you by name.

***

## Credential Rotation Playbook

When API credentials, signing keys, or sessions need to be rotated, follow the appropriate procedure. The full playbook is in [credential-architecture.md](/docs/prd-shared/credential-architecture.md) Section 6; this is the quick reference.

### API Credential Rotation (Minutes, Zero Downtime)

| Provider  | Steps                                                                                                         | Impact                                             |
| --------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Privy** | 1. Generate new App Secret in Privy Dashboard. 2. Update `PRIVY_APP_SECRET` in `.env`. 3. Restart MCP server. | Old secret immediately invalid. Wallet unaffected. |

### Signing Key Rotation (Minutes, No Address Change)

For smart contract wallets, signing key rotation happens on-chain. The wallet address does not change. No ERC-721 Transfer event is emitted. Identity and reputation are fully preserved.

* **ERC-4337 (ZeroDev Kernel)**: Call `setOwner(newAddress)` via UserOp from the sudo key.
* **Safe**: Call `swapOwner(prevOwner, oldOwner, newOwner)` with threshold signatures.

### Identity Transfer (7+ Days, Reputation Impact)

Only as a last resort. Prefer signing key rotation on a smart contract wallet.

1. `DANGER__requestTransfer(tokenId, recipient)` -- 7-day cooldown starts
2. Guardian can veto during cooldown
3. After cooldown, 48-hour execution window
4. **Reputation impact**: Drops to near-zero, recovers linearly over 30 days

***

## Emergency Runbook

### Agent Compromised (Prompt Injection Suspected)

1. **Immediate**: If using time-delayed proxy, monitoring bot auto-cancels suspicious announcements
2. **Within minutes**: Call `identityGuardian.freezeCredential(tokenId)` from any guardian address -- revokes all vault access instantly
3. **Within hours**: Rotate signing key on the smart contract wallet (see above). Revoke API credentials at provider dashboard.
4. **Assessment**: Review all pending proxy announcements. Cancel any unrecognized transactions.

### API Credentials Compromised

1. **Immediate**: Revoke/rotate credentials at the provider dashboard (Privy)
2. **Within minutes**: Update `.env` on the agent machine. Restart MCP server.
3. **Assessment**: Policy engine constrains what the attacker could have signed. Review on-chain activity since compromise window.

### Unknown Transaction Detected

1. **If using time-delayed proxy**: The monitoring bot's cancel authority vetoes the pending announcement immediately
2. **If direct execution**: Freeze credential via guardian. The transaction may have already executed on-chain.
3. **Post-incident**: Review spending limit counters. Check if daily/session limits were approached. Tighten policy.

### Provider Outage

1. Wallet is a smart contract on-chain -- funds are safe during any provider outage
2. Cannot sign new transactions until the provider recovers
3. If extended outage: guardians can initiate key rotation to migrate signing authority to a different provider
4. Read-only MCP tools (pool data, positions, balances) continue to work -- they don't require signing