> 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/gotts-vaults/vault/02-personas.md).

# Agent Roles and Personas

> **Part of**: [Vault PRD](/docs/gotts-vaults/vault.md) | **Last Updated**: 2026-02-21
>
> **See also**: [shared/user-journeys.md](/docs/prd-shared/user-journeys.md) — market-segment personas, funnel analysis, friction taxonomy, and end-to-end journey maps for depositors, agent operators, vault creators, managers, and developers.

***

## Three Protocol Roles

Every agent interacting with the protocol occupies one or more of three roles:

| Role                  | What They Do                                                                           | Who They Are                                        |
| --------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Vault Creator**     | Deploys vaults via the factory, configures strategy parameters, earns management fees  | Agents with market insight and a thesis to monetize |
| **Vault Manager**     | Executes strategy — CCA bidding, LP management, rebalancing. Authorized by the creator | Specialist execution agents hired by creators       |
| **Vault Participant** | Deposits capital, receives ERC-4626 shares, earns yield                                | Capital-rich agents seeking returns                 |

A single agent can hold all three roles across different vaults (e.g., creator of Vault A, participant in Vault B, manager of Vault C).

***

## Agent Personas

### Persona 1: The Strategy Agent (Creator + Manager)

**Who**: An AI agent that autonomously detects yield opportunities, deploys vaults via the factory to capture them, and manages positions actively.

**Needs**:

* Scan CCA auctions for high-quality token launches
* Deploy "CCA Hunter" vaults when promising auctions appear
* Submit collective bids, manage the auction lifecycle, and deploy post-graduation LP
* Earn management fees (2% AUM) and performance fees (20% above HWM)

**Example workflow**: Agent monitors CCA factory for new auctions → evaluates token quality, graduation likelihood → calls `create_vault` with CCA-enabled config → calls `submit_cca_bid` when auction opens → manages bid lifecycle → claims tokens → deploys LP → attracts depositors via strong track record.

### Persona 2: The Curator Agent (Creator)

**Who**: An agent with deep market expertise that curates vault strategies and sets parameters but delegates execution to specialist manager agents.

**Needs**:

* Create vaults with well-defined strategies and risk parameters
* Assign manager roles to specialized trading agents
* Maintain a high reputation score to attract depositors
* Set reputation-gated access (e.g., minimum 50 reputation to deposit)

**Example workflow**: Curator agent creates a "Blue Chip CCA" vault with strict risk parameters (max 10% per auction, only curated auctions) → hires a trading agent as manager → the curator's reputation (score 120) allows charging 2% management + 20% performance → depositors choose this vault for its conservative approach.

### Persona 3: The Trading Agent (Manager)

**Who**: A specialist execution agent that focuses on optimal bid sizing, LP rebalancing, and exit timing. Hired by vault creators.

**Needs**:

* Deep V4 hook expertise for LP position management
* CCA bid optimization (timing, price levels, checkpoint management)
* Multi-vault management — may be the assigned manager for several vaults simultaneously
* Earn reputation from successful execution across vaults

**Example workflow**: Trading agent is assigned as manager on 3 vaults → monitors positions across all 3 → rebalances when positions go out of range → manages CCA bid lifecycle for CCA-enabled vaults → builds execution reputation that leads to more vault assignments.

### Persona 4: The Allocator Agent (Participant)

**Who**: A capital-rich agent (e.g., a treasury management agent, a self-funding agent with idle capital) that selects vaults based on creator reputation and risk-adjusted returns.

**Needs**:

* Discover vaults via `list_vaults` and `get_vault_rankings`
* Evaluate creator reputation, historical Sharpe ratio, and risk parameters
* Deposit into the best-performing vaults matching risk tolerance
* Diversify across multiple vaults with different risk profiles

**Example workflow**: User tells their OpenClaw/Claude agent "make money, figure things out" → agent calls `get_vault_rankings` → filters by minimum creator reputation (50+) and vault Sharpe ratio → deposits across top 3 vaults (one conservative, one moderate, one CCA-focused) → monitors performance → rebalances allocation quarterly.

### Persona 5: The Meta-Vault Agent (Creator + Participant)

**Who**: An agent that creates a vault-of-vaults — its strategy is allocating across other protocol vaults, following the Theoriq AlphaVault pattern.

**Needs**:

* Create a meta-vault that deposits into other protocol vaults
* Evaluate and rank underlying vaults by performance, risk, and liquidity
* Rebalance allocation across underlying vaults based on changing conditions
* Offer diversified exposure to depositors who want a "set and forget" experience

**Example workflow**: Meta-vault agent creates a vault → uses `get_vault_rankings` to identify top 5 performing vaults → deposits proportionally → rebalances monthly → depositors get diversified exposure across strategies without selecting individual vaults.

### Persona 6: The Arbitrage Agent (Participant)

**Who**: An agent that exploits price differences between vault share tokens and their underlying NAV. With auto-created V4 share pools and NAVAwareHook pricing, this agent plays a critical ecosystem role: keeping share prices aligned with true vault value across all factory-deployed vaults.

**Needs**:

* Monitor NAV vs pool price across all factory vaults via `SharePoolClient.listSharePools()` and `getNAVDiscount()`
* Detect persistent discounts (shares trading below NAV) and premiums (shares trading above NAV)
* Execute single-vault arbitrage: buy underpriced shares on V4 pool → redeem via `vault_withdraw` → capture spread
* Execute cross-vault arbitrage: buy underpriced Vault A shares → redeem for underlying → deposit into overpriced Vault B → sell Vault B shares on V4 pool
* Use Universal Router flash accounting for atomic multi-hop execution (no intermediate token transfers)

**Example workflow (single-vault)**: NAVAwareHook reports Vault A shares at $0.97 (3% discount to NAV of $1.00) → agent buys shares on V4 pool at $0.97 + 5 bps fee → redeems via `vault_withdraw` at $1.00 NAV → captures \~2.95% spread after fees. This arbitrage self-corrects the mispricing.

**Example workflow (cross-vault)**: Vault A shares at 98% NAV, Vault B shares at 101% NAV (same underlying: USDC) → agent constructs Universal Router command batch: buy Vault A shares → redeem for USDC → deposit USDC into Vault B → sell Vault B shares → net profit \~2.5% after fees. Entire operation settles atomically via V4 flash accounting.

**Flywheel contribution**: Every arbitrage trade is Uniswap volume on vault share pools. The protocol becomes a self-correcting market for vault shares — mispricings create profit opportunities that generate volume, which generates fees for LPs, which attracts more share pool liquidity, which tightens spreads.

### Persona 7: The Autonomous Yield Agent (Participant)

**Who**: An AI agent that autonomously manages treasury capital, seeking yield on idle capital to fund its own compute costs.

**Needs**:

* Deposit into vaults and receive shares proportional to contribution
* Receive strategy recommendations and auto-rebalance
* Collect and compound LP fees
* Track performance over time (APY, drawdown, IL)

**Example workflow**: Agent deposits 10,000 USDC → vault mints shares → vault manager deploys capital into V4 LP positions → fees auto-compound → agent withdraws with yield after 30 days.

### Persona 8: The Strategy Provider Agent

**Who**: An agent that analyzes Uniswap pools, publishes rebalancing strategies, and earns x402 micropayments when other agents consume them.

**Needs**:

* Publish strategy endpoints gated by x402 ($0.01–$0.10 per query)
* Provide volatility analysis, rebalance recommendations, and APY estimates
* Earn USDC revenue from strategy consumers
* Build reputation from successful strategy outcomes

**Example workflow**: Strategy agent analyzes pool volatility → publishes rebalance recommendation at x402-gated endpoint → other vault agents pay via x402 to access → agent earns USDC → successful outcomes increase reputation score.

### Persona 9: The Agent Developer

**Who**: A developer building vault-interacting agents using the TypeScript SDK or MCP tools. Uses Claude Code, Cursor, or similar AI-assisted development tools.

**Needs**:

* Clear SDK documentation with TypeScript types
* One-command local testnet with factory deployed, multiple vaults created, agents registered
* Debug UI to visualize vault state, factory registry, and CCA positions
* Standalone vault MCP server that runs independently for focused development
* Multi-agent simulation environment to test agent-to-agent interactions (deposits, reputation feedback, vault creation competition)
* Minimal scripts to spawn, stop, and monitor autonomous agents locally

**Example workflow**: Developer runs `pnpm testnet:swarm` → 5 agents spin up with different strategies (creator, conservative allocator, aggressive yield chaser, newbie, meta-vault operator) → watches agents compete for vault deposits in real-time via debug UI → inspects agent activity feed and interaction graph → modifies agent profiles to test edge cases → validates behavior → moves to Base testnet → deploys to mainnet.

### Persona 10: The New Agent Operator

**Who**: A developer or power user setting up their first autonomous agent to earn yield. May be using OpenClaw, Claude Desktop, or a custom MCP-compatible agent. Has never interacted with Uniswap programmatically. Wants to go from zero to earning yield as fast as possible without compromising security.

**Needs**:

* One-command wallet creation with no key management (e.g., `npx awal`)
* Guided identity registration (single transaction, clear metadata format)
* Pre-configured security policies with safe defaults (TEE-enforced, vault-only allowlist)
* Clear "what can go wrong" documentation and security checklist
* Graduation path from Simple Yield to advanced strategies as confidence grows
* Immediate, tangible reputation progress from first interaction — visible path to Basic tier

**Example workflow**: Follows [00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) → provisions a Privy server wallet on Base → registers ERC-8004 identity (one transaction, \~$0.01) → enrolls in reputation engine (bundled with identity registration, \~$0.01) → applies vault-participant policy template (vault + USDC + identity + reputation engine contracts) → deposits 500 USDC into top Simple Yield vault → **First Deposit milestone auto-triggers** (reputation score 70, visible progress toward Basic tier) → monitors position via MCP tools → **after 30 days, Steady Staker milestone auto-triggers** (score 75, agent reaches Basic tier: 10x deposit cap, 5% fee discount) → graduates to LP Manager vault or deposits into reputation-gated vaults now accessible at Basic tier.

### Persona 11: The Vault Auditor Agent

**Who**: A read-only agent that monitors vault health, positions, and risk metrics across the factory. Never executes transactions.

**Needs**:

* Query vault state (TVL, share price, positions, APY) across all factory vaults
* Monitor position health (in-range status, IL risk, concentration)
* Track historical performance (returns, drawdown, Sharpe ratio)
* Alert when circuit breaker thresholds are approaching

**Example workflow**: Agent calls `list_vaults` -> iterates through all vaults calling `vault_get_state` and `vault_get_risk_metrics` -> reports TVL, APY, IL across the factory -> alerts operator if any vault's NAV drawdown exceeds 8% (approaching 10% circuit breaker).

### Persona 12: The Watchdog Agent (Cancel Authority)

**Who**: A monitoring agent that watches `TransactionAnnounced` events across all proxy-managed agent wallets. Runs 24/7 on redundant infrastructure. Has no ability to submit, modify, or execute transactions -- can only cancel suspicious ones. This is the reactive counterpart to preventive security measures.

**Needs**:

* Multi-provider WebSocket connections for redundant event detection (Alchemy + QuickNode + Infura)
* Tenderly Web3 Action as managed backup detection layer
* Automated policy evaluation engine (whitelist check, value threshold, pattern detection)
* Optional Tenderly simulation of pending transactions before making cancel/allow decisions
* Multi-channel alerting (Telegram, Discord, PagerDuty) with configurable severity routing
* False-positive tracking and policy tuning based on historical data
* KMS-backed cancel authority key management (AWS KMS, HashiCorp Vault)

**Example workflow**: Monitoring bot detects `TransactionAnnounced(txId: 47, agent: 0xAgent, target: 0xUnknown, value: 27.7 ETH)` -> evaluates: target address is not on any whitelist -> auto-cancel fires immediately via `proxy.cancel(47)` -> alerts operator on Telegram: "CANCELLED tx #47: 27.7 ETH transfer to unknown address 0xUnknown..." -> operator investigates, revokes agent proxy permissions if compromise confirmed.

**Security properties**: If the watchdog's cancel key is compromised, the attacker can only prevent legitimate transactions (denial of service) -- they cannot initiate, modify, or execute any transaction. This is a deliberately asymmetric design.

### Persona 13: The Reputation Builder Agent

**Who**: An agent whose primary objective is building on-chain reputation to access gated, high-performance vaults. This agent systematically participates across multiple vaults to earn milestones and climb reputation tiers. May be a treasury agent that views reputation as a strategic asset, or a new agent operator following the "grind to Verified" path.

**Needs**:

* Discover starter vaults with `minReputation=0` and low minimum deposits
* Track milestone progress via `vault_get_milestones` — see what's earned, what's claimable, what's in progress
* Claim milestones efficiently (ideally auto-triggered, but can manually claim unclaimed milestones)
* Understand the concrete path from current tier to next tier (how many more milestones, how much time)
* Identify reputation-gated vaults that become accessible at each tier level

**Example workflow**: Agent enrolls in reputation engine (one-time, \~$0.01) → deposits $1,000 into 3 starter vaults (Simple Yield, `minReputation=0`) → First Deposit milestone auto-triggers on first vault (score 70) → within days, Diversifier milestone triggers (3+ vaults, score 80) → calls `vault_get_milestones` to check progress: estimated score 15, Basic tier reached → holds for 30 days, Steady Staker triggers on each vault → now at Verified-adjacent score → completes a profitable exit on one vault (Profitable Exit, score 80) → calls `vault_get_milestones`: estimated score 55, Verified tier reached → accesses reputation-gated CCA Hunter vault requiring `minReputation=50` → earns higher yields while continuing to build toward Trusted tier.

**Why this persona matters**: This agent represents the viral growth loop. Every Reputation Builder is simultaneously a vault depositor (TVL), a multi-vault participant (network density), and an eventual vault creator (ecosystem breadth). The reputation grind is the on-ramp that converts new entrants into power users.

### Persona 14: The Passive Depositor (Human-Adjacent)

**Who**: An agent operator — possibly a non-technical user — who wants "deposit and forget" with the simplest possible mental model. This persona treats vault shares as tradeable yield-bearing tokens on Uniswap, not as positions in a complex DeFi protocol. May never interact with vault contracts directly. The auto-created V4 share pool is their primary interface.

**Needs**:

* Discover vault share tokens via standard Uniswap token discovery (search, pool browsing)
* Buy vault shares on Uniswap V4 like any other token swap — the NAVAwareHook ensures fair pricing at NAV ± spread
* Hold shares and earn yield passively (share price appreciates as vault generates returns)
* Sell shares on Uniswap V4 instantly when they want to exit — no withdrawal queue, no vault interaction
* See clear, simple information: current price, yield rate, vault creator reputation
* Never need to understand LP positions, tick ranges, CCA auctions, or rebalancing

**Example workflow**: User tells their agent "buy 500 USDC worth of that yield vault token" → agent calls `SharePoolClient.buySharesViaPool()` → receives vault shares at NAV + 5 bps → shares appreciate as vault earns yield → after 30 days, user says "sell my vault tokens" → agent calls `SharePoolClient.sellSharesViaPool()` → receives USDC instantly at NAV - 25 bps → done. No registration, no identity check for pool trading (identity check happens at the hook level only for direct vault deposits).

**Why this persona matters**: This is the key onboarding simplification. The mental model goes from "register identity → configure wallet → deposit into vault → monitor positions → call withdraw" to "buy a token, hold it, sell it." Every complexity is hidden behind the V4 pool and NAVAwareHook. This persona is the growth unlock — any agent that can trade tokens on Uniswap can participate in vault yield without understanding the vault protocol at all.

**Constraints**: Trading via the share pool incurs slightly higher fees (NAV spread + swap fees) than direct vault deposit/withdraw. For large positions, direct vault interaction remains more efficient. The share pool route is optimized for simplicity, not cost.

***

## Persona-Role Mapping

| Persona            | Role                      | Description                                                           |
| ------------------ | ------------------------- | --------------------------------------------------------------------- |
| Strategy Agent     | Creator + Manager         | Detects opportunities, deploys vaults, manages positions              |
| Curator Agent      | Creator                   | Curates strategy, delegates execution to specialist managers          |
| Trading Agent      | Manager                   | Execution specialist: optimal bid sizing, LP rebalancing, exit timing |
| Allocator Agent    | Participant               | Selects vaults by creator reputation and Sharpe ratio                 |
| Meta-Vault Agent   | Creator + Participant     | Vault-of-vaults allocator                                             |
| Arbitrage Agent    | Participant               | Exploits share token pricing inefficiencies                           |
| Yield Agent        | Participant               | Autonomous treasury management, seeks yield on idle capital           |
| Strategy Provider  | External                  | Publishes x402-gated strategy endpoints                               |
| Developer          | External                  | Builds vault-interacting agents using SDK/MCP                         |
| New Agent Operator | External (onboarding)     | First-time setup, follows quickstart, graduates to advanced           |
| Auditor Agent      | External (read-only)      | Monitors vault health across the factory                              |
| Watchdog Agent     | External (cancel-only)    | Monitors proxy announcements, cancels suspicious transactions         |
| Reputation Builder | Participant (multi-vault) | Systematically builds reputation through broad vault participation    |
| Passive Depositor  | Participant (pool-based)  | Buys/sells vault share tokens on Uniswap V4 — simplest UX path        |

***

## Persona Progression Map

Personas are not static — agents and operators naturally progress through multiple personas as they gain experience and reputation. Three canonical progression arcs describe how users evolve within the Gotts ecosystem:

* **New-to-Sovereign Arc**: From zero reputation through all five tiers, with concrete milestones and time estimates at each stage.
* **Operator-to-Creator Arc**: When a Participant should consider becoming a Creator — triggered by identifying yield opportunities not served by existing vaults.
* **Developer-to-Operator Arc**: The "first agent" transition moment — when a developer's local testnet experience leads to deploying a real agent on Base.

For detailed journey maps, friction analysis, funnel metrics, and stage-by-stage emotional context for each progression arc, see [shared/user-journeys.md](/docs/prd-shared/user-journeys.md) Section 10.