> 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/user-journeys.md). # User Journeys > **Document Type**: REF (informative) | **Last Updated**: 2026-02-21 > > **Cross-references**: [vault/02-personas.md](/docs/gotts-vaults/vault/02-personas.md), [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md), [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md), [vault/15-metrics.md](/docs/gotts-vaults/vault/15-metrics.md), [shared/onboarding-workflow.md](/docs/prd-shared/onboarding-workflow.md) *** ## 1. Purpose and Scope This document maps the end-to-end experience for humans and agents arriving at Gotts — from first awareness through sustained participation. It bridges the **market-segment personas** (who is coming) with the **protocol-role personas** (what they do once here) and identifies friction points at every stage. **What this covers:** * Funnel stages from awareness to advocacy * Friction taxonomy (universal, agent-specific, human-specific) * Five detailed journey maps for priority personas * Cross-persona progression arcs * Competitive UX benchmarks grounded in market data **What this does NOT cover:** * Normative requirements — those live in the linked PRDs. This document uses MAY, SHOULD, and RECOMMENDED language only. * Technical onboarding steps — see [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) for canonical onboarding paths * Contract specifications — see [vault/06-contracts.md](/docs/gotts-vaults/vault/06-contracts.md) **How to use this document:** Product design and UX decisions should reference this doc to understand who the user is, what they feel at each stage, and where they drop off. Prioritization decisions should weight frictions by severity and addressable segment size. *** ## 2. Persona Taxonomy: Two Layers Gotts serves two distinct persona layers. Layer 1 describes *who arrives* (market segments defined by capital, sophistication, and motivation). Layer 2 describes *what they do* (protocol roles defined by on-chain actions). A single person or agent may occupy one market segment but hold multiple protocol roles across different vaults. ### Layer 1 — Market Segments Seven personas segmented by capital size, technical sophistication, and primary motivation: | Segment | Capital | Sophistication | Primary Motivation | | -------------------------------- | ---------- | -------------- | ------------------------------------------------------ | | **Passive Yield Seekers** | $1K–$100K | Low–Medium | "Set and forget" yield on idle capital | | **Crypto-Native Power Users** | $50K–$1M+ | High | Sophisticated strategies with transparent control | | **DAO Treasury Managers** | $1M–$500M+ | Team-based | Fiduciary duty, audit trails, governance integration | | **Institutional Allocators** | $10M+ | Conservative | KYC/AML compliance, permissioned access, reporting | | **AI Agent Operators** | Variable | Very High | Deploy autonomous agents to earn yield | | **Developers / Integrators** | N/A | High | Build on top of the protocol (SDK, hooks, tools) | | **Strategy Creators / Curators** | Variable | Very High | Monetize DeFi expertise via vault creation or curation | **Passive Yield Seekers** represent the largest addressable segment — analogous to Yearn depositors. They need simple flows, transparent metrics, and understandable risk indicators. **Crypto-Native Power Users** want sophisticated strategies they cannot build themselves while retaining control over risk parameters. They value strategy transparency, agent behavior explainability, and composability (vault tokens as collateral elsewhere). **DAO Treasury Managers** operate under fiduciary duty across $30B+ in collective treasury assets. They require multi-sig compatibility, governance integration, and audit trails. **Institutional Allocators** represent 11.5% of DeFi TVL today (projected 32.55% CAGR through 2031). They need KYC/AML compliance and institutional custody integration. Note: Aave Arc's $50K TVL is a cautionary example — permissioned architecture alone does not guarantee institutional flows. **AI Agent Operators** deploy and manage autonomous agents. They need agent deployment tools, policy configuration, monitoring dashboards, and reputation systems. **Developers / Integrators** (3,532 monthly active DeFi developers per Electric Capital) build on the protocol. They need well-documented SDKs, sandbox environments, and the ability to reach their first successful integration within 10 minutes. **Strategy Creators / Curators** bridge quantitative finance and DeFi knowledge. They mirror Morpho's vault curators and Yearn's community strategy writers. ### Layer 2 — Protocol Roles The 14 protocol-role personas are defined in [vault/02-personas.md](/docs/gotts-vaults/vault/02-personas.md). They describe the on-chain actions agents perform: Strategy Agent, Curator Agent, Trading Agent, Allocator Agent, Meta-Vault Agent, Arbitrage Agent, Yield Agent, Strategy Provider, Developer, New Agent Operator, Auditor Agent, Watchdog Agent, Reputation Builder, and Passive Depositor. ### Mapping: Market Segment → Protocol Roles | Market Segment | Primary Protocol Role(s) | Journey Archetype | Entry Point | | ---------------------------- | ----------------------------------------------------------------- | -------------------------- | ----------------------------------------------- | | Passive Yield Seekers | Passive Depositor (14), Allocator Agent (4) | Buy-and-hold | Uniswap UI, vault explorer, agent command | | Crypto-Native Power Users | Allocator Agent (4), Reputation Builder (13) | Evaluate-deposit-monitor | Vault explorer, CLI, SDK | | DAO Treasury Managers | Allocator Agent (4), Meta-Vault Agent (5) | Governance-approve-deposit | Multi-sig proposal, vault explorer | | Institutional Allocators | Allocator Agent (4) | Compliance-review-deposit | Permissioned vault, direct integration | | AI Agent Operators | New Agent Operator (10), Yield Agent (7), Reputation Builder (13) | Zero-to-yield | `npx @gotts.ai setup`, Claude Desktop, OpenClaw | | Developers / Integrators | Developer (9) | Docs-setup-integrate | Documentation, SDK, `pnpm testnet` | | Strategy Creators / Curators | Strategy Agent (1), Curator Agent (2), Strategy Provider (8) | Design-deploy-attract | Vault factory, SDK, am-AMM auction | *** ## 3. The Funnel: Awareness to Advocacy Seven stages with definitions, success criteria, and known drop-off rates from market data. ### Stage Definitions | Stage | Definition | Success State | Known Drop-Off | | ------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------- | | **1. Awareness** | Learns Gotts exists (social, referral, aggregator listing, agent discovery) | Visits docs or vault explorer | — | | **2. Discovery** | Finds a specific vault or tool that matches their need | Identifies a target vault or integration opportunity | — | | **3. Evaluation** | Assesses risk, yield, trust signals (creator reputation, TVL, audit status) | Decides to proceed | \~70% drop-off at wallet creation (industry-wide) | | **4. Onboarding** | Wallet + identity + policy setup | Ready to transact | \~80% abandon at bridging (industry-wide) | | **5. First Action** | First deposit, first tool call, or first share purchase | On-chain confirmation received | — | | **6. Retention** | Ongoing participation, reputation growth, strategy evolution | Active at 30/90-day marks | — | | **7. Advocacy** | Refers others, creates vaults, publishes strategies, contributes to ecosystem | Vault creation, referral, or integration published | — | ### Cross-Persona Funnel Mechanisms Each cliff in the funnel maps to a specific Gotts mechanism designed to address it: | Funnel Cliff | Severity | Gotts Mechanism | PRD Reference | | -------------------------------- | ---------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Wallet creation drop-off (\~70%) | High | Embedded wallets (Privy), gasless ERC-4337 batch onboarding, counterfactual addresses | [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) §Fast Paths | | Bridging abandonment (\~80%) | High | Base-first deployment (sub-cent gas), auto-routing | [shared/chains.md](/docs/prd-shared/chains.md) | | Gas anxiety | Medium | Paymaster sponsorship (up to $15K credits), ERC-20 paymasters for USDC gas | [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) §FAQ | | Trust gap (unknown protocol) | High | ERC-8004 creator reputation, factory verification (`factory.isVault()`), audit status | [vault/02-personas.md](/docs/gotts-vaults/vault/02-personas.md), [vault/10-safety.md](/docs/gotts-vaults/vault/10-safety.md) | | DeFi vocabulary overload | Medium | Progressive disclosure — Passive Depositor path hides all complexity behind "buy a token" | Section 5 below | | Withdrawal uncertainty | Medium | Three exit paths (instant, async request, force exit) + V4 share pool secondary market | [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) §FAQ | | Reputation tier grind | Low–Medium | Auto-attested milestones, visible progress, concrete tier requirements | [vault/02-personas.md](/docs/gotts-vaults/vault/02-personas.md) §Persona 13 | *** ## 4. Friction Taxonomy Three categories of friction, prioritized by severity and mapped to Gotts mechanisms. ### 4.1 Universal Frictions Frictions affecting all users regardless of whether they are humans or agents. | Friction | Severity | Description | | ---------------------- | -------- | -------------------------------------------------------------------------- | | Wallet creation | High | 70% of new DeFi users abandon at wallet connection | | Gas / bridging | High | 80% refuse to bridge assets cross-chain; gas costs eat into small deposits | | Key management anxiety | High | Fear of losing keys, no recovery path, "what if I mess up" | | Trust gap | High | New protocol, no track record, "is my money safe?" | | Withdrawal uncertainty | Medium | "Can I get my money out when I want?" | | Multi-chain confusion | Medium | Which chain, which token address, which RPC | ### 4.2 Agent-Specific Frictions Frictions unique to AI agent operators deploying autonomous agents. | Friction | Severity | Description | | -------------------------- | ---------- | ----------------------------------------------------------------------------------------- | | Credential management | High | API keys in plaintext JSON files, no standard secret management | | Policy configuration | High | Defining what the agent can and cannot do, fear of over/under-permissioning | | MCP server deployment | Medium | Running a persistent server, choosing transport, monitoring health | | ERC-8004 unfamiliarity | Medium | New standard (launched Jan 2026), unclear benefits, unfamiliar registration flow | | Reputation tier grind | Medium | Starting at $1,000 deposit cap feels limiting; path to higher tiers feels long | | Prompt injection fear | Medium | "What if someone tricks my agent into draining my wallet?" | | Agent monitoring | Low–Medium | No standard way to observe what the agent is doing and why | | No UI available (headless) | Medium | Agent on remote server via SSH — no browser, no display, no interactive prompts | | Chat-only interface | Medium | Agent via Telegram/Discord — sequential messages only, no forms or browsers | | Environment detection | Low | Agent cannot reliably determine display/shell/config availability for auto-mode selection | ### 4.3 Human-Specific Frictions Frictions unique to human depositors interacting through UIs or agents. | Friction | Severity | Description | | ------------------------- | -------- | --------------------------------------------------------------------------- | | DeFi vocabulary overload | High | Ticks, hooks, sqrtPriceX96, ERC-4626 — jargon barrier is immediate | | Opaque risk | High | Cannot assess what "yield" means, where it comes from, or what can go wrong | | No familiar trust signals | Medium | No brand recognition, no FDIC, no support phone number | | Strategy complexity | Medium | LP positions, rebalancing, impermanent loss — too many concepts at once | | Withdrawal queue anxiety | Medium | "Will I be stuck?" especially during market stress | ### 4.4 Friction → Mechanism → PRD Reference Complete mapping from each friction point to the Gotts mechanism that addresses it, the PRD section that specifies it, and gap status. | Friction | Gotts Mechanism | PRD Reference | Gap Status | | ---------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | Wallet creation (70% drop-off) | Embedded wallets (Privy), gasless ERC-4337 batch, `npx @gotts.ai setup` wizard | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md), [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) | Addressed | | Gas / bridging (80% abandon) | Base-first (sub-$0.01 gas), paymaster sponsorship ($15K credits), ERC-20 paymasters | [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) §Fast Paths, [shared/chains.md](/docs/prd-shared/chains.md) | Addressed | | Key management anxiety | TEE-backed wallets (Privy), operator holds keys (never agent), smart wallet key rotation | [shared/credential-architecture.md](/docs/prd-shared/credential-architecture.md), [vault/03-custody.md](/docs/gotts-vaults/vault/03-custody.md) | Addressed | | Trust gap | ERC-8004 reputation tiers, factory verification, circuit breakers, 15-layer safety | [vault/10-safety.md](/docs/gotts-vaults/vault/10-safety.md), [shared/safety-layers.md](/docs/prd-shared/safety-layers.md) | Addressed | | Withdrawal uncertainty | Three exit paths + V4 share pool secondary market + ERC-7540 async receipts | [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) §FAQ | Addressed | | Multi-chain confusion | Base as primary chain, auto-chain detection, ChainCapabilities system | [shared/chains.md](/docs/prd-shared/chains.md) | Addressed | | Credential management | Install wizard generates `.env`, per-provider credential validation | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) | Addressed | | Policy configuration | Named policy presets (Participant, Manager, Creator), TEE-enforced | [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) §Step 3, [shared/credential-architecture.md](/docs/prd-shared/credential-architecture.md) | Addressed | | MCP server deployment | One-command deploy (`npx @gotts.ai setup`), health check tool | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md), [mcp-server/14-deployment.md](/docs/gotts-safe-mcp-server/mcp-server/14-deployment.md) | Addressed | | ERC-8004 unfamiliarity | Wizard offers optional registration, clear handle/metadata guidance | [shared/onboarding-workflow.md](/docs/prd-shared/onboarding-workflow.md) §Step 2 | Addressed | | Reputation tier grind | Auto-attested milestones (First Deposit = 70 pts), visible progress via `vault_get_milestones` | [vault/02-personas.md](/docs/gotts-vaults/vault/02-personas.md) §Persona 13 | Addressed | | Prompt injection fear | PolicyCage (on-chain boundaries), TEE-enforced signing policies, CaMeL dual-LLM defense | [vault/10-safety.md](/docs/gotts-vaults/vault/10-safety.md), [vault/19-threat-model.md](/docs/gotts-vaults/vault/19-threat-model.md) | Addressed | | Agent monitoring | Debug UI, `vault_get_state`, `vault_get_performance`, agent activity feed | [vault/05-local-dev.md](/docs/gotts-vaults/vault/05-local-dev.md) | Addressed | | DeFi vocabulary overload | Passive Depositor path ("buy a token, hold it, sell it"), progressive disclosure | Section 5 below | Addressed | | Opaque risk | NAV transparency, circuit breaker thresholds, risk metrics tools | [vault/08-mcp-tools.md](/docs/gotts-vaults/vault/08-mcp-tools.md) | Addressed | | No familiar trust signals | Creator reputation scores, TVL as social proof, factory verification | [vault/02-personas.md](/docs/gotts-vaults/vault/02-personas.md) | Partially addressed — website trust signals `[Deferred]` | | Strategy complexity | Template system (Simple Yield first), graduation path | [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) §Graduation Path | Addressed | | Withdrawal queue anxiety | Instant share pool exit, force exit option, receipt NFT for async | [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) §FAQ | Addressed | | Human-readable signing | Transaction simulation before every write, balance change preview | [vault/10-safety.md](/docs/gotts-vaults/vault/10-safety.md) | Partially addressed — signing UX detail `[Deferred]` | | No UI available (headless) | `--non-interactive` mode, OpenClaw skill with env detection, `--zero` for instant start | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Agent-Driven Setup | Addressed | | Chat-only interface | Chat state machine (5-7 states), `--from-config` for produced config | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Chat App Setup Protocol | Addressed | | Environment detection | `hasDisplay()`, `hasConfigFile()`, `hasExistingSetup()` in OpenClaw skill | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Pattern C | Addressed | | Onboarding for DAOs / institutions | Multi-sig compatible flows, permissioned vaults | — | `[Deferred]` to post-v1 | *** ## 5. Journey: Passive Depositor ("Buy Yield Like Any Token") The highest-priority UX gap. This journey serves the largest addressable segment: Passive Yield Seekers. ### Who Non-technical users (or their agents) who want yield on idle capital without understanding DeFi mechanics. Their mental model: **vault shares are tradeable yield-bearing tokens on Uniswap** — no different from buying any other token. ### Mental Model ``` "I buy a token. It goes up over time because the vault earns yield. When I want out, I sell the token. That's it." ``` This mental model is accurate. Vault shares are ERC-20 tokens. The NAVAwareHook prices them at net asset value ± a small spread. Share price appreciates as the vault generates returns. ### Two Entry Paths | | A) Buy Shares via V4 Pool | B) Direct ERC-4626 Deposit | | --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | | **User experience** | Swap USDC for vault shares on Uniswap — identical to any token swap | Call `vault.deposit()` — protocol interaction, identity check | | **Identity required** | No (pool-based trading has no ERC-8004 gate) | Yes (ERC-8004 registration required) | | **Reputation earned** | No (protocol cannot attribute the purchase) | Yes (First Deposit milestone triggers) | | **Cost** | NAV spread (\~50 bps) + swap fee | Gas only (\~$0.01 on Base) | | **Exit** | Sell on pool (instant) | `vault_withdraw` or sell on pool | | **Best for** | Small amounts, zero friction, "just try it" | Larger amounts, wants reputation, lower fees | Path A is the **growth unlock**. Any agent that can trade tokens on Uniswap can participate in vault yield without understanding the vault protocol at all. ### Journey Stages **Stage 1: Discovery** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Browsing Uniswap token lists, vault explorer, or asking their agent "find me yield" | | What are they thinking? | "I have idle USDC. Can I earn something without locking it up or learning DeFi?" | | What friction do they hit? | Vocabulary overload if exposed to LP/tick/hook terminology | | What does Gotts do? | Vault share tokens appear as standard tokens on Uniswap; vault explorer shows APY, TVL, creator reputation in simple terms | | Success state | User identifies a vault share token with acceptable yield and TVL | **Stage 2: Evaluation** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------- | | What is the user doing? | Checking yield (APY), safety (TVL, creator reputation), and exit options | | What are they thinking? | "Is this legit? Can I lose money? How do I get out?" | | What friction do they hit? | Trust gap — unknown protocol, no brand recognition | | What does Gotts do? | Factory verification badge, creator reputation score, circuit breaker disclosure, transparent fee structure | | Success state | User decides to proceed — yield/risk ratio acceptable, exit path clear | **Stage 3: Entry (Path A — Pool-Based)** | Question | Answer | | -------------------------- | --------------------------------------------------------------------------------------------------- | | What is the user doing? | Swapping USDC for vault shares on Uniswap V4 — same flow as any token swap | | What are they thinking? | "This is just a swap. I know how to do this." | | What friction do they hit? | None beyond standard Uniswap swap friction (gas, slippage) | | What does Gotts do? | NAVAwareHook ensures fair pricing at NAV ± spread; LaunchFeeHook protects early depositors from MEV | | Success state | User holds vault share tokens in their wallet | **Stage 3 (alt): Entry (Path B — Direct Deposit)** | Question | Answer | | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Registering ERC-8004 identity (if not already), then depositing via `vault_deposit` | | What are they thinking? | "I want the best rate and I want to build reputation" | | What friction do they hit? | Identity registration step (unfamiliar), Permit2 approval | | What does Gotts do? | OnboardRouter batches identity + approval + deposit into single gasless UserOp; First Deposit milestone auto-triggers | | Success state | User holds vault shares and has earned first reputation milestone (70 points) | **Stage 4: Holding** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Checking share price occasionally, watching yield accumulate | | What are they thinking? | "Is it working? Am I making money?" | | What friction do they hit? | Lack of familiar portfolio views, unclear yield attribution | | What does Gotts do? | Share price appreciation is passive feedback; `vault_get_performance` shows APY, P< vault explorer shows position value | | Success state | User sees positive yield over 30 days, trusts the system | **Stage 5: Exit** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | What is the user doing? | Selling shares on V4 pool (Path A) or calling `vault_withdraw` (Path B) | | What are they thinking? | "I want my money back, now" | | What friction do they hit? | Withdrawal queue anxiety (Path B only if idle capital insufficient) | | What does Gotts do? | Path A: instant swap, no queue. Path B: three options (instant if idle available, async request with receipt NFT, force exit with penalty). Both paths always available. | | Success state | USDC received, yield realized | ### Progression ``` Passive Depositor (pool-based, no identity) → registers ERC-8004 identity (for reputation and fee discounts) → direct depositor (lower fees, earns reputation) → Reputation Builder (multi-vault diversification) → higher-tier strategies (LP Manager, CCA Hunter) → possibly Vault Creator (once at Verified tier) ``` The key insight: the passive depositor path is a **free trial** that costs nothing to try and naturally leads to deeper engagement as users gain confidence. *** ## 6. Journey: New Agent Operator ("Zero to Yield") The most complex journey. This builds on [vault/00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) but adds the UX/emotional layer. ### Who AI Agent Operators 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. ### Entry Points | Mode | Entry Point | UI Available | Human Required | Best For | | ------------------- | --------------------------------------- | ------------------------- | --------------------- | ----------------------------- | | **Terminal wizard** | `npx @gotts.ai setup` | Terminal (@clack/prompts) | Yes (5 questions) | Most operators | | **Browser wizard** | `npx @gotts.ai setup --ui` | Browser (localhost:3456) | Yes (visual guided) | Operators who prefer GUI | | **Zero-dependency** | `npx @gotts.ai setup --zero` | Terminal (zero questions) | No | Quick evaluation, testing | | **Agent headless** | `npx @gotts.ai setup --non-interactive` | None | No (env vars pre-set) | Remote servers, SSH | | **OpenClaw skill** | "Set up Gotts" | Auto-detected | Depends on env | OpenClaw agents (any surface) | | **Chat app** | "@bot setup gotts" | Messaging app | Yes (sequential Q\&A) | Telegram/Discord/Slack users | All modes produce identical output. See [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) for the full specification. ### Pre-Journey: The Decision Before any technical step, the operator is asking: *"Can this work? Is it safe to give an agent access to my money?"* **Information needs at this stage:** * How much capital is at risk? (Deposit caps provide a natural safety net: $1,000 at Unverified tier) * What happens if the agent is compromised? (PolicyCage, TEE-enforced policies, time-delayed proxy) * Can I turn it off instantly? (Freeze credential, halt agents) * What's the minimum viable investment of time? (< 5 minutes via wizard) ### Journey Stages **Stage 1: Setup** | Question | Answer | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Running `npx @gotts.ai setup` (or `--ui`, `--zero`, `--non-interactive`, OpenClaw skill, or chat), answering 0-5 questions depending on mode | | What are they thinking? | "Let me see if this works. I'm not committing real money yet." | | What friction do they hit? | Terminal: provider credential creation (one-time dashboard visit). Zero-dep: none. Headless: env var setup. Chat: sequential message pacing. | | What does Gotts do? | Wizard auto-creates wallet (or generates local key for `--zero`), generates config, applies safe-default policy, starts MCP server, runs health check. All modes converge to identical output. | | Success state | MCP server running, wallet created (or local key for `--zero`), health check passing (< 5 min terminal, < 30 sec zero-dep) | **Stage 2: Identity** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Registering ERC-8004 identity (wizard offers this as optional step) | | What are they thinking? | "What is ERC-8004? Do I need this?" | | What friction do they hit? | Unfamiliar standard, unclear benefits at this stage | | What does Gotts do? | Wizard explains in one line: "Identity lets your agent build reputation and access better vaults." Registration is one transaction (\~$0.01 on Base). | | Success state | Agent has on-chain identity, Agent ID returned | **Stage 3: Policy** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Reviewing (or accepting defaults for) wallet security policy | | What are they thinking? | "I want this locked down. What can go wrong?" | | What friction do they hit? | Policy language is technical; fear of misconfiguration | | What does Gotts do? | Named presets (vault-participant: only deposit/withdraw + USDC + identity contracts). Policy applied automatically by wizard. TEE enforcement means even a compromised agent cannot exceed bounds. | | Success state | Policy applied, unauthorized operations provably rejected | **Stage 4: First Deposit** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Depositing into a Simple Yield vault (wizard offers this, or agent does it via natural language) | | What are they thinking? | "Small amount first. Let me see what happens." | | What friction do they hit? | USDC funding (need USDC on Base), deposit cap surprise ($1,000 at Unverified) | | What does Gotts do? | Wizard finds best vault automatically, simulates before executing, First Deposit milestone auto-triggers (70 reputation points) | | Success state | Deposit confirmed, shares received, first milestone earned, visible progress toward Basic tier | **Stage 5: Reputation Grind** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | What is the user doing? | Holding position, checking milestones, possibly depositing into additional vaults | | What are they thinking? | "How do I unlock higher deposit caps? How long does this take?" | | What friction do they hit? | Path to next tier feels unclear without explicit guidance | | What does Gotts do? | `vault_get_milestones` shows concrete progress: earned milestones, next-tier requirements, estimated time. Auto-attested milestones remove manual claiming burden. | | Success state | Agent reaches Basic tier (10+ reputation, \~30 days), deposit cap increases to $10,000 | **Stage 6: Graduation** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Expanding wallet policy to include new contract addresses, enabling additional MCP tools | | What are they thinking? | "I trust this now. I want more yield / more strategies." | | What friction do they hit? | Policy expansion requires understanding which contracts to allowlist | | What does Gotts do? | Graduation path documentation with explicit policy diff for each level. Each upgrade is two changes: policy allowlist + tool profile. | | Success state | Agent operating at LP Manager, CCA Hunter, or Creator level | ### Fast Path vs Understanding Path | Path | Steps | Time | Cost | Best For | | --------------------------------------- | ----------------------- | -------------- | --------------- | ------------------------------------ | | **Fast Path** (ERC-4337 batch) | 1 wizard run + 1 UserOp | < 5 min total | $0 (paymaster) | "Just make it work" | | **Understanding Path** (explicit steps) | 4 separate transactions | < 10 min total | \~$0.04 on Base | "I want to know what each step does" | The wizard defaults to the fast path. Operators who choose "No, customize" in the wizard get the understanding path. ### Reputation Progression Map | Milestone | Score | Cumulative | Tier Reached | Estimated Time | | --------------------------- | ---------------- | ---------------- | -------------------- | -------------- | | First Deposit | 70 pts | \~7 (normalized) | Unverified | Day 1 | | Diversifier (3+ vaults) | 80 pts | \~15 | Basic (10+) | Week 1–2 | | Steady Staker (30-day hold) | 75 pts per vault | \~30–40 | Basic | Month 1 | | Profitable Exit | 80 pts | \~45–55 | Approaching Verified | Month 2–3 | | Diamond Hands (90-day hold) | 85 pts | \~55+ | Verified (50+) | Month 3 | | Vault Creator | 90 pts | \~65+ | Verified | Month 3+ | | Peer feedback accumulation | Variable | \~100+ | Trusted (100+) | Month 6+ | | Sustained track record | Variable | \~500+ | Sovereign (500+) | 12+ months | ### Common Failure Modes | Failure | Symptom | Resolution | | ------------------------- | -------------------------------------- | ----------------------------------------------------------------- | | No gas on Base | Deposit transaction fails | Fund wallet with ETH (or use paymaster-sponsored path) | | Policy misconfiguration | Vault contract calls rejected | Apply named preset via wizard; check contract allowlist | | Deposit cap surprise | "Max deposit exceeded" error at $1,001 | Understand tier system; start within $1,000 cap; build reputation | | MCP server not running | Agent cannot call tools | Run `pnpm dev` or `npx @gotts.ai safe` to restart; check health | | Privy credentials expired | Wallet signing fails | Rotate App Secret in Privy Dashboard; update `.env` | *** ## 6b. Journey: Remote Agent Operator ("Headless OpenClaw") ### Who Operators running OpenClaw or a custom agent framework on remote servers via SSH. No browser, no display, no interactive terminal UI. Common in production deployments, cloud VMs, and co-located infrastructure. ### Journey Stages **Stage 1: Environment Preparation** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | SSH into remote server, setting env vars (`PRIVY_APP_ID`, `PRIVY_APP_SECRET`, `ALCHEMY_API_KEY`) | | What are they thinking? | "I need this agent running unattended. No GUI." | | What friction do they hit? | Must pre-configure credentials via SSH before setup can run | | What does Gotts do? | `--non-interactive` flag reads all config from env vars. If credentials are missing, `--zero` provides immediate read-only access while credentials are arranged. | | Success state | Env vars set, ready to run wizard | **Stage 2: Autonomous Setup** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Running `npx @gotts.ai setup --non-interactive` (or OpenClaw skill auto-detects headless and runs it) | | What are they thinking? | "This should just work without me sitting here" | | What friction do they hit? | Credential validation failures surface as exit codes, not interactive prompts | | What does Gotts do? | Full wizard execution: wallet creation, config generation, policy application, server start, health check — all non-interactive. Exit code 0 on success, non-zero with structured error JSON on failure. | | Success state | MCP server running as background process, health check passing | **Stage 3: Verification and Monitoring** | Question | Answer | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Verifying setup via MCP tools (`check_setup_health`) or SSH-forwarded Portal (`npx @gotts.ai portal --port 3002`) | | What are they thinking? | "Is it working? Can I monitor it remotely?" | | What friction do they hit? | No local browser for Portal — requires SSH port forwarding or remote URL | | What does Gotts do? | `check_setup_health` returns structured JSON verifiable from any MCP client. Portal can be accessed via SSH tunnel (`ssh -L 3002:localhost:3002 server`). | | Success state | Agent operational, monitoring established | ### Key Design Requirement The headless path MUST work end-to-end with zero interactive prompts. Every question the terminal wizard asks must have a CLI flag or env var fallback. The OpenClaw `setup-gotts-agent` skill handles environment detection and mode selection automatically. See [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Agent-Driven Setup for the technical specification. *** ## 6c. Journey: Chat-Based Setup ("Telegram/Discord") ### Who Users interacting with a Gotts agent exclusively through a messaging app. No terminal, no browser — just sequential chat messages with numbered options. ### Constraints * No forms, no multi-field inputs — one question per message, one answer per reply * Numbered options for structured choices (e.g., "Reply 1, 2, or 3") * Credentials should NOT be pasted into chat — detect pre-configured env vars or instruct operator to set them on the bot server * Total flow: 5-7 messages ### Journey Stages **Stage 1: Intent** ``` Bot: "Welcome to Gotts setup! What should your agent do? 1. Earn yield in vaults 2. Trade tokens 3. Manage liquidity 4. Development / testing" User: "1" ``` **Stage 2: Wallet** ``` Bot: "Wallet provider: 1. Privy (recommended — TEE-backed) 2. Skip for now (read-only, instant start)" User: "3" ``` **Stage 3: Confirmation** ``` Bot: "Setup summary: • Intent: Earn yield in vaults • Wallet: Zero-dependency (read-only) • RPC: Public endpoints Reply 'go' to execute or 'edit' to change." User: "go" ``` **Stage 4: Execution** ``` Bot: "Setting up... ✓ Generated local key ✓ Started MCP server (data profile, 28 tools) ✓ Health check passed Your agent is ready (read-only mode). Wallet: 0x1a2B...3c4D To upgrade to full access: set PRIVY_APP_ID and PRIVY_APP_SECRET on the bot server, then send 'upgrade gotts'." ``` ### Security Note Recommend env vars on the bot server rather than credentials pasted into chat messages. If credentials are pre-configured, the chat flow skips credential prompts entirely with a message: "Using pre-configured Privy credentials." See [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Chat App Setup Protocol for the full state machine definition. *** ## 6d. Journey: Quick Evaluator ("Zero-Dependency") ### Who Curious developers and agent operators who want to try Gotts before committing to wallet provider accounts. They want to see what the data tools can do — pool info, token prices, trade history — without creating any external accounts. ### Journey Stages **Stage 1: Instant Setup (30 seconds)** | Question | Answer | | -------------------------- | --------------------------------------------------------------------------------------------------- | | What is the user doing? | Running `npx @gotts.ai setup --zero` | | What are they thinking? | "Let me see what this can do before I sign up for anything" | | What friction do they hit? | None — zero questions, zero accounts | | What does Gotts do? | Generates local key, starts data-profile MCP server, connects to public RPCs, outputs client config | | Success state | MCP server running, 28 read-only tools available, < 30 seconds from command to first tool call | **Stage 2: Exploration (5-10 minutes)** | Question | Answer | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Asking their AI client questions: "What's the price of ETH?", "Show me the top pools on Base", "Find me yield opportunities" | | What are they thinking? | "This is actually useful. The data is good." | | What friction do they hit? | Write operations return "upgrade required" errors — intentional nudge toward full setup | | What does Gotts do? | Every "upgrade required" error includes a one-liner: `Re-run npx @gotts.ai setup to enable write operations.` | | Success state | User has explored the data layer, understands the tool surface, sees value | **Stage 3: Upgrade Decision** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Deciding whether to upgrade to full setup | | What are they thinking? | "I want to actually trade / deposit / manage liquidity" | | What friction do they hit? | Must create a Privy account (one-time, \~3 min) | | What does Gotts do? | `npx @gotts.ai setup` detects existing zero-dep config, offers in-place upgrade. Preserves client config — only adds wallet and write tools. | | Success state | Full setup complete, write operations enabled, zero-dep config upgraded in place | ### Key Metric Zero-dep to full setup conversion: **>40% within 7 days**. The zero-dep path is a free trial that naturally leads to full adoption. *** ## 7. Journey: Vault Creator ("Deploy and Attract Capital") ### Who Strategy Creators or Crypto-Native Power Users who want to monetize DeFi expertise by deploying vaults and attracting depositors. ### Prerequisites * Verified tier recommended (50+ reputation) — not enforced but signals credibility to depositors * Capital for initial seed deposit (creator typically seeds their own vault) * Understanding of at least one strategy template ### Journey Stages **Stage 1: Strategy Thesis** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Identifying a yield opportunity — e.g., "USDC Simple Yield on Base earns 4% but I can get 6% with active LP management" | | What are they thinking? | "I know something the market doesn't. Can I package this into a vault?" | | What friction do they hit? | Assessing whether the opportunity is real, backtesting limitations | | What does Gotts do? | Research tools (`get_pool_info`, `get_token_price_history`), risk assessment (`vault_get_risk_metrics`), competitive analysis (`list_vaults` to see existing yield rates) | | Success state | Clear strategy thesis with target yield, risk parameters, and asset selection | **Stage 2: Vault Design** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Choosing template, fee structure, access controls | | What are they thinking? | "What fee can I charge without scaring away depositors?" | | What friction do they hit? | Template selection (which template fits?), fee calibration | | What does Gotts do? | Template comparison (Simple Yield, LP Manager, CCA Hunter, Full Stack, Meta-Vault), fee caps disclosure (5% management, 50% performance), competitive fee benchmarks | | Success state | Vault configuration finalized | **Stage 3: Deployment** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Calling `create_vault` via MCP tools or SDK | | What are they thinking? | "Is this going to work? What if I make a mistake?" | | What friction do they hit? | CREATE2 deployment, V4 pool auto-creation, initial seed amount | | What does Gotts do? | Factory handles all deployment complexity; auto-creates V4 share pool; LaunchFeeHook protects early trading; Creator milestone auto-triggers | | Success state | Vault deployed, V4 share pool live, creator receives Creator milestone | **Stage 4: Seeding** | Question | Answer | | -------------------------- | ---------------------------------------------------------------------------------------- | | What is the user doing? | Depositing initial capital to demonstrate confidence | | What are they thinking? | "I need skin in the game for credibility" | | What friction do they hit? | How much to seed (too little looks uncommitted, too much is capital-inefficient) | | What does Gotts do? | Factory recommends minimum seed based on template; creator's deposit is visible on-chain | | Success state | Vault has initial TVL, share pool has liquidity | **Stage 5: Attracting Depositors** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Building reputation, sharing performance, listing on aggregators | | What are they thinking? | "How do I get my first external depositor?" | | What friction do they hit? | Cold start problem — no track record yet | | What does Gotts do? | ERC-8004 reputation as trust signal, factory listing, aggregator discovery (vaults.fyi, DefiLlama), share token composability | | Success state | External depositors arrive; TVL grows beyond seed capital | **Stage 6: Operating** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Executing strategy, collecting fees, managing risk, reporting to depositors | | What are they thinking? | "Am I outperforming? Are depositors happy?" | | What friction do they hit? | Ongoing strategy execution, fee collection timing, circuit breaker management | | What does Gotts do? | Vault MCP tools for state monitoring, performance tracking, fee collection; PolicyCage enforces boundaries; circuit breaker provides automatic risk management | | Success state | Sustained positive performance, growing TVL, growing reputation | ### Key Decision: am-AMM Participation Vault creators may choose to enable am-AMM (auction-managed AMM) for strategy management rights. Under this model, a third party can bid to manage the vault's strategy via Harberger lease — the winner pays continuous rent to depositors as real yield. The creator still sets the PolicyCage boundaries but delegates execution. *** ## 8. Journey: Vault Manager ("Win Bids, Execute Strategy") ### Who Trading Agents or Strategy Providers who specialize in execution. They earn fees by managing other people's vaults, not by deploying capital. ### Entry Point am-AMM auction bid or curator assignment. The manager role is separate from creator — a manager may never deploy their own vault. ### Journey Stages **Stage 1: Discovery** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------- | | What is the user doing? | Scanning am-AMM auctions for vaults that match their strategy expertise | | What are they thinking? | "Which vaults can I manage profitably?" | | What friction do they hit? | Evaluating vault parameters, understanding PolicyCage constraints | | What does Gotts do? | `list_vaults` with strategy filter, vault config inspection, PolicyCage parameter disclosure | | Success state | Identifies target vault with favorable parameters and manageable constraints | **Stage 2: Evaluation** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------- | | What is the user doing? | Analyzing vault economics — fee potential, TVL, rent cost, competition | | What are they thinking? | "Can I make money here after paying rent?" | | What friction do they hit? | Rent economics unclear, competition from other bidders | | What does Gotts do? | Transparent auction state, historical rent/yield data, fee structure visibility | | Success state | Positive expected return after rent and costs | **Stage 3: Bid** | Question | Answer | | -------------------------- | ---------------------------------------------------------------------------------------- | | What is the user doing? | Submitting am-AMM bid with proposed rent and strategy parameters | | What are they thinking? | "Am I bidding too much? Too little?" | | What friction do they hit? | Bid calibration, Harberger dynamics unfamiliarity | | What does Gotts do? | `submit_cca_bid` (or equivalent am-AMM tool), bid simulation, competitive bid visibility | | Success state | Bid submitted, position in auction clear | **Stage 4: Win and Operate** | Question | Answer | | -------------------------- | --------------------------------------------------------------------------------------------- | | What is the user doing? | Executing strategy within PolicyCage bounds — rebalancing, LP management, fee collection | | What are they thinking? | "Execute well, build reputation, attract more assignments" | | What friction do they hit? | PolicyCage constraints, gas optimization, time-delayed proxy requirements | | What does Gotts do? | Vault MCP tools for execution, proxy module for time-delayed operations, performance tracking | | Success state | Vault performance exceeds benchmark, rent paid, reputation growing | **Stage 5: Renewal** | Question | Answer | | -------------------------- | --------------------------------------------------------------------------------------------- | | What is the user doing? | Defending management position in ongoing Harberger auction | | What are they thinking? | "My track record should justify my position" | | What friction do they hit? | Being outbid by a competitor with deeper capital | | What does Gotts do? | Reputation-weighted bidding advantages (fee discounts), track record visibility to depositors | | Success state | Retained management position, or graceful transition to new manager | ### Reputation Flywheel ``` Good execution → higher reputation → more vault assignments → fee discounts → competitive advantage → more execution opportunities ``` *** ## 9. Journey: Developer / Integrator ### Who Developers building vault-interacting agents, custom hooks, or protocol integrations using the TypeScript SDK or MCP tools. Uses Claude Code, Cursor, or similar AI-assisted development tools. ### Entry Point Documentation, SDK package, `pnpm testnet` command. ### Journey Stages **Stage 1: Discover API** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Reading docs, scanning tool list, understanding what's possible | | What are they thinking? | "What can I build with this? How does it compare to what I know?" | | What friction do they hit? | Documentation volume, unclear "where to start" | | What does Gotts do? | `00-quickstart.md` as canonical entry point, clear SDK/tool reference (`08-mcp-tools.md`), LLM-optimized docs | | Success state | Developer understands the API surface and identifies their integration point | **Stage 2: Local Setup** | Question | Answer | | -------------------------- | --------------------------------------------------------------------------------------- | | What is the user doing? | Running `pnpm testnet` to spin up local Anvil with full Uniswap stack + vault factory | | What are they thinking? | "Does this actually work? Can I get a local environment running?" | | What friction do they hit? | Dependencies, build failures, port conflicts | | What does Gotts do? | One-command testnet with all contracts deployed, mock tokens seeded, debug UI available | | Success state | Local environment running, debug UI accessible, factory deployed with seed vaults | **Stage 3: First Integration** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Making their first vault query or deposit via SDK or MCP tools | | What are they thinking? | "Let me see if the SDK types are good and the API makes sense" | | What friction do they hit? | Type coverage gaps, unclear error messages, parameter confusion | | What does Gotts do? | TypeScript-first SDK with full type coverage, structured error codes with actionable messages, Zod validation | | Success state | First successful vault query or simulated deposit (target: < 10 minutes from docs) | **Stage 4: Test** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Writing integration tests against local testnet, testing edge cases | | What are they thinking? | "Does this handle failures correctly? What about gas estimation?" | | What friction do they hit? | Fork testing setup, time-travel for yield testing, multi-agent scenarios | | What does Gotts do? | `pnpm testnet:swarm` for multi-agent simulation, `timeTravel` utilities, vitest fixtures, Foundry fork testing patterns | | Success state | Integration tests pass, edge cases handled | **Stage 5: Production** | Question | Answer | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Deploying to Base Sepolia (testnet) then Base (mainnet) | | What are they thinking? | "Am I confident this works in production?" | | What friction do they hit? | Testnet vs mainnet parameter differences, contract address management | | What does Gotts do? | Per-chain address constants, ChainCapabilities system, deployment guide ([vault/18-deployment.md](/docs/gotts-vaults/vault/18-deployment.md)) | | Success state | Integration live on Base mainnet | ### Target Benchmark Following Uniswap's documentation design target: **< 10 minutes from docs to first successful vault query**. Every guide should reference runnable code. Links should be footnoted to minimize distraction. *** ## 9b. Journey: Agent Operator Monitors Performance ("The Dashboard Loop") ### Who AI Agent Operators with a deployed agent (post-wizard setup). Uses the Portal dashboard to monitor agent performance, review decisions, steer strategy, and investigate anomalies. Maps to the "AI Agent Operators" market segment. ### Entry Point ```bash npx @gotts.ai portal # Or: portal.gotts.ai (hosted, for dev/testing) ``` ### Journey Stages **Stage 1: Connect to MCP Server** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Running `npx @gotts.ai portal` which reads `.env` for MCP server URL and API key | | What are they thinking? | "Let me see what my agent has been doing" | | What friction do they hit? | First-time setup: understanding API key tiers, choosing Feedback key vs Read key | | What does Gotts do? | Portal auto-detects key tier from prefix, adjusts UI capabilities, runs health check, shows connection status | | Success state | Dashboard home loads with summary metrics: portfolio value, reputation tier, active vaults, pending proxy announcements | **Stage 2: Review Portfolio & P\&L** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Checking portfolio value, P\&L breakdown, gas costs | | What are they thinking? | "Am I making money? How much am I spending on gas?" | | What friction do they hit? | Data latency if MCP server is remote; unfamiliar metrics | | What does Gotts do? | Portfolio section shows balances across all chains, historical value chart, P\&L breakdown (realized/unrealized/fees/gas), benchmark comparison | | Success state | Operator understands current financial position and trend | **Stage 3: Investigate Audit Trail** | Question | Answer | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Reviewing the chronological log of all agent actions | | What are they thinking? | "What exactly has my agent been doing? Were there any failures?" | | What friction do they hit? | High volume of entries; need good filtering | | What does Gotts do? | Audit trail with filters (date, type, tool, success/failure), expandable rows showing full parameters and response JSON, transaction hashes linked to block explorer | | Success state | Operator can trace any agent decision to its inputs, outputs, and on-chain result | **Stage 4: Browse Memory & Insights** | Question | Answer | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Exploring what the agent has learned — browsing episodes and semantic insights | | What are they thinking? | "What does my agent 'know'? Has it learned anything wrong?" | | What friction do they hit? | Large memory stores; need semantic search | | What does Gotts do? | Episode browser with vector search, insight browser with category/confidence filters, memory stats (episode count, consolidation status) | | Success state | Operator identifies any bad insights or missing knowledge, understands agent's "mental model" | **Stage 5: Submit Feedback** | Question | Answer | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Giving the agent a directive based on what they observed | | What are they thinking? | "I need to steer the agent — it's being too aggressive / missing an opportunity" | | What friction do they hit? | Feedback requires Feedback key (Read key operators see this step disabled) | | What does Gotts do? | Structured feedback form: strategy preference, decision correction, market context, goal adjustment. Stored as high-priority semantic insight. Agent retrieves on next context injection cycle. | | Success state | Directive submitted, visible in active directives list, agent behavior adjusts on next cycle | **Stage 6: Ongoing Monitoring** | Question | Answer | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | What is the user doing? | Returning daily/weekly to check the dashboard | | What are they thinking? | "Is the agent following my directives? Is performance improving?" | | What friction do they hit? | No notifications for important events (deferred to Phase W5) | | What does Gotts do? | Dashboard home shows delta since last visit, feedback directives have status indicators, vault involvement tracks ongoing performance | | Success state | Operator develops trust in agent autonomy, reduces check frequency over time | ### The Dashboard Loop ``` npx @gotts.ai portal │ ├── Dashboard Home → portfolio value, reputation, health check │ ├── Drill into Portfolio → balances, P&L, gas analysis │ ├── Review Audit Trail → recent actions, failures, on-chain results │ ├── Browse Memory → what the agent has learned, bad insights │ ├── Submit Feedback → steer agent behavior │ └── Check back later → verify feedback took effect ``` *** ## 10. Cross-Persona Progression Journeys Three arcs showing how users grow over time within the Gotts ecosystem. ### Arc 1: New-to-Sovereign ("The Reputation Grind") The path from zero reputation to Sovereign tier, with concrete milestones: ``` Day 1 │ Register identity, first deposit │ Score: ~7 Tier: Unverified Cap: $1,000 │ Week 2 │ Diversify into 3+ vaults │ Score: ~15 Tier: Basic Cap: $10,000 │ Month 1 │ Steady Staker milestone on first vaults │ Score: ~30 Tier: Basic │ Month 3 │ Diamond Hands + Profitable Exit + Diversifier │ Score: ~55 Tier: Verified Cap: $50,000 │ Month 6 │ Vault Creator milestone + peer feedback │ Score: ~100 Tier: Trusted Cap: $100,000 │ Year 1+ │ Sustained track record across multiple roles │ Score: 500+ Tier: Sovereign Cap: Unlimited ``` **Key transitions:** * **Unverified → Basic** (\~30 days): First deposit + Steady Staker. The most important conversion — user commits real capital and stays. * **Basic → Verified** (\~3 months): Diamond Hands + Diversifier + Profitable Exit. Demonstrates sustained, profitable participation. * **Verified → Trusted** (\~6 months): Vault creation + peer feedback. Transition from participant to ecosystem contributor. * **Trusted → Sovereign** (12+ months): Institutional-grade track record. Very few agents should reach this tier. ### Arc 2: Operator-to-Creator ("From Using to Building") When a Participant should consider becoming a Creator: ``` Participant Phase (Months 1-3) ├── Depositing into multiple vaults ├── Learning strategy patterns from vault performance data ├── Reaching Verified tier (50+ reputation) └── Identifying yield opportunities not served by existing vaults │ ▼ Transition Trigger: "I can do better than the vaults I'm depositing into" │ ▼ Creator Phase (Month 3+) ├── Deploy first vault with conservative parameters ├── Seed with own capital (skin in the game) ├── Build track record over 30-60 days └── Attract external depositors via reputation signal ``` **Signal that the transition is working:** The creator's vault attracts depositors from other vaults based on superior risk-adjusted returns. ### Arc 3: Developer-to-Operator ("The First Agent Moment") The transition from building *on* the protocol to running agents *in* the protocol: ``` Developer Phase ├── Building integration using SDK ├── Running testnet:swarm locally ├── "Wait, I could run one of these agents for real" │ ▼ Transition Trigger: "What if my agent just... kept running?" │ ▼ Operator Phase ├── Deploy agent with Privy wallet on Base ├── Register ERC-8004 identity ├── Start with Simple Yield vault participation ├── Expand to LP Manager or CCA Hunter as confidence grows └── Eventually: build custom strategies that leverage their unique integration ``` This arc is particularly valuable because developer-operators bring technical understanding that enables them to build differentiated strategies. *** ## 11. Competitive UX Benchmarking Market data grounding the UX decisions above. ### Pendle Earn: Simplified Deposit → 20x TVL Growth Pendle achieved 20x TVL growth and 400% user growth by launching Pendle Earn — a simplified deposit-and-earn interface that hides PT/YT tokenization mechanics from casual users while keeping advanced trading available. The pattern: **simple interface layered on top of complex protocol**, not a dumbed-down protocol. **What Gotts borrows:** Progressive disclosure — Passive Depositor path hides vault mechanics behind "buy a token." Advanced users can access direct deposit, reputation building, strategy configuration, and vault creation. ### Ethena: Atomic Staking → Fastest Stablecoin Growth Ethena achieved the fastest stablecoin growth to $10B supply in 500 days through an atomic staking flow — USDe → sUSDe in one wallet signature — combined with a points program (Shard Campaign) attracting 41,000+ initial users. **What Gotts borrows:** One-step entry. The ERC-4337 batch onboarding collapses wallet creation + identity + deposit into a single gasless operation (< 30 seconds). Reputation milestones function as a non-extractive "points" equivalent. ### Morpho: Curator Model for Trust Delegation Morpho's MetaMorpho vaults ($5.8B TVL, 2,700+ vaults) rely on curated vaults managed by risk experts alongside raw permissionless markets. They explicitly acknowledge: "one interface cannot satisfy the needs for every user persona." **What Gotts borrows:** Curator Agent persona (Persona 2). Vault creators set parameters and delegate execution to specialist managers. Reputation tiers provide the trust signal that Morpho's curators provide via off-chain brand. ### Yearn V3: Single vs Multi-Strategy Vault Choice Yearn V3 uses ERC-4626-compliant tokenized strategies where users choose single-strategy vaults (simpler, targeted risk) or multi-strategy allocator vaults. **What Gotts borrows:** Template system. Simple Yield (single-strategy), LP Manager, CCA Hunter, Full Stack, Meta-Vault (multi-strategy allocator). Users choose complexity level explicitly. ### Where Gotts Differentiates | Differentiator | Competitor Status | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Auto-created V4 share pools** | No competitor offers instant secondary market for vault shares via Uniswap. Passive Depositor path is unique. | | **ERC-8004 agent reputation** | No competitor gates vault access by on-chain agent reputation. Trust is currently based on off-chain brand (Morpho curators, Yearn strategists). | | **am-AMM strategy management** | No competitor uses Harberger lease auctions for vault management rights. Bunni v2 validates the mechanism (\~59% of V4 hook volume). | | **Passive Depositor path** | No competitor enables zero-registration vault yield via standard token swap. | | **PolicyCage** | No competitor has on-chain hard boundaries for AI agent strategy with immutable contract constraints. | *** ## 12. Success Metrics for Journeys Per-archetype metrics cross-referenced to [vault/15-metrics.md](/docs/gotts-vaults/vault/15-metrics.md). ### Onboarding Funnel Conversion | Metric | Target | Measurement | PRD Reference | | ---------------------------------------------------- | ------ | ---------------- | --------------------------------------------------------------------------------------------------------------- | | Wizard completion rate (start → health check pass) | > 80% | Wizard telemetry | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Success Metrics | | Identity registration rate (when prompted by wizard) | > 50% | Wizard telemetry | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Success Metrics | | Vault deposit rate (when prompted by wizard) | > 30% | Wizard telemetry | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Success Metrics | ### Time-to-First-Action | Journey | Metric | Target | PRD Reference | | ---------------------------------- | ------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------- | | Passive Depositor (pool path) | Time from "find yield" to share purchase | < 2 minutes | — | | New Agent Operator (fast path) | Zero to first deposit | < 5 minutes | [vault/15-metrics.md](/docs/gotts-vaults/vault/15-metrics.md) §B | | New Agent Operator (explicit path) | Identity to first deposit | < 10 minutes | [vault/15-metrics.md](/docs/gotts-vaults/vault/15-metrics.md) §B | | Developer | Docs to first successful vault query | < 10 minutes | Uniswap benchmark | | Vault Creator | Strategy thesis to vault deployed | < 30 minutes | — | | Quick Evaluator (zero-dep) | `npx --zero` to first successful tool call | < 30 seconds | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Success Metrics | ### Retention | Metric | 30-Day Target | 90-Day Target | PRD Reference | | --------------------------------------------------- | ------------- | ------------- | ------------- | | Depositor retention (active position at 30/90 days) | > 60% | > 40% | — | | Agent operator retention (agent still running) | > 70% | > 50% | — | | Vault creator retention (vault still active) | > 80% | > 70% | — | | Developer retention (integration still deployed) | > 50% | > 30% | — | ### Progression | Metric | Target | PRD Reference | | ------------------------------------- | --------------------- | ---------------------------------------------------------------- | | Unverified → Basic conversion rate | > 40% within 60 days | [vault/15-metrics.md](/docs/gotts-vaults/vault/15-metrics.md) §C | | Basic → Verified conversion rate | > 20% within 6 months | [vault/15-metrics.md](/docs/gotts-vaults/vault/15-metrics.md) §C | | Participant → Creator conversion rate | > 5% within 6 months | — | | Single-vault → multi-vault depositors | > 30% within 90 days | — | ### Journey Health Indicators | Indicator | Healthy | Unhealthy | Action | | ------------------------------------- | --------------------------- | ------------------------ | ------------------------------------- | | Wizard abandonment step | Distributed across steps | Concentrated at one step | Fix that step's UX | | Time-to-first-deposit distribution | Tight cluster around target | Long tail of stragglers | Investigate blockers | | Deposit cap complaints | Rare | Frequent | Consider tier threshold adjustments | | Passive → direct depositor conversion | Steady growth | Flat | Improve identity registration UX | | Reputation milestone claim rate | > 80% of eligible | < 50% of eligible | Auto-claim or improve discoverability | ### Multi-Modal Setup | Metric | Target | PRD Reference | | ----------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- | | Zero-dep to full setup conversion rate | > 40% within 7 days | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Success Metrics | | Browser wizard completion rate (`--ui`) | > 85% | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Success Metrics | | Chat-based setup completion rate (S1→S7) | > 60% | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Success Metrics | | Agent-driven setup success rate (headless / OpenClaw) | > 95% | [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) §Success Metrics |